Preprocessing Paragraphs: A Beginner's Guide

welcome to pre-processing paragraphs a

beginner's guide very excited to go

through this let's get started

a couple of things at the top the slides

are posted on the mid camp session so if

you want to download them and follow

along there I'd recommend it also I have

a github sample repo the things that

we're going to be going through today

it's a bit easier to see some of the

text if you open it up on your text

editor since some of the lines are

really small in on the screen so I just

heads-up those two things a little bit

about me first though this is my dog

buco that we just adopted recently my

name is Larry of a long time

I'm a senior developer at chromatic you

can follow me at twitter chromatic just

a little bit about them we are a fully

distributed team now we work with drupal

javascript a bunch of web tech doing

some interesting things we have an

awesome blog and the Twitter presence so

check us out follow us along the game

probably comment to leave this up just

for a second it's a sample module that I

have created where we kind of go through

what we're going to be going through

here today you'll be able to see the

code in further context so it's get IL /

f jf6

y just gonna leave this up here for a

sec

a sensitive no yeah

and while we're waiting and final thing

I have some time left for questions at

the end so if you just want a hold of

your questions at the end and if we run

out of time feel free to come up to me

and talk to me and I'll be happy to talk

through some of the things that we're

going through today what's that supposed

to be

that's what I got you come on Rhonda

I am sorry about this

since she's pretty important it's

supposed to go and look like this

interesting yes it's like gonna have

that calm get to io / f jf 6 wide this

is like the short link that they created

that I pasted which yeah if you search

for me on github well anytime kinetic

paragraphs is a repo there sorry about

this

whereas both the whole URL may be big

good idea

for the recording github.com / wala and

gita n / chromatic underscore of

paragraphs

we we all said that's sorry about this

technical difficulty good all right yeah

so let's step back into the session a

few learning outcomes this is what I

hope everyone takes away from our

session today first is that you'll be

able to pre-process paragraphs and

structure your RP processing methods

will be going through some custom

renderer arrays and how we override the

tweak templates we're gonna talk briefly

about reference nested entities so inode

references or taxonomy references how do

we pull that data into our template for

paragraphs and finally debugging our

pre-processing in our tweet files

without running out of memory or in

calculating the white screen of death

first a few prereqs so all I ask and

hope that you're just familiar with

Jubilees that can mean like you just

have opened it installed it have an idea

what it is

twig the templating language and tweak

files that power the mark-up for Drupal

familiarity with PHP and also the

paragraphs module as well so let's do a

really quick overview of what the

paragraphs module is essentially when

you install it you are given this entity

with configurable fields the

configurable just like nodes you can

create fields on them they have

different types so you can have multiple

different types of paragraphs just like

you can have multiple different types of

nodes and they all have specific view

modes that you can create to customize

your layout now with pre-processing

we're going to be talking about a full

customization and we're not going to be

using view modes at all so this is an

example like what a paragraph could look

like in your Drupal admin there's

several paragraphs here first we have a

text paragraph at the top with a handful

of fields below it is a quote paragraph

and then below that is a slideshow so

you can structure in your fields however

you want them and when they output to

the page this is a visual representation

of what those paragraphs would look like

so on the right is your your web page as

viewable in their client

and on the left is the paragraphs that

can pose that webpage that you can

configure you can move them around we're

going to be talking about styling and

pre-processing so that we have full

control over how these are represented

on the webpage so pre-processing when we

boil it down it's essentially just data

transformation so we get our field data

and we want to do something with it

also we are separating our concerns so

the logic that we have all lives outside

of the template now twig is super

powerful and there's a lot of things

that we can do within twig to transform

the data or filter it or do multiple

things we're going to be doing all of

this within our preprocessor instead of

twig and finally customization this is

the custom markup that we're going to be

writing and we're outputting as render

arrays now render arrays are what twig

consumes and presents on the webpage so

first we have a few things to get

started we would need to download and

install a paragraphs module configure a

paragraph just like you couldn't figure

any sort of note or entity and then

finally create a custom module I'm sorry

about the sample repo and this is all

setup there and we're going to be

talking about this pre-processing the

recipe so I wanted to take some of the

knowledge that I learned from a client

and how we approached it and apply it to

the talk so with each paragraph we're

going to apply four steps first is in

our hook theme in our custom module we

define the paragraph type second we're

going to be handling all of our

pre-processing inside of a class third

inside of that class each paragraph type

is going to have a corresponding method

where we actually do the transformations

and and the full pre-processing

and then finally we're linking it up

back to our tweak template with a

corresponding paragraph template

now we're going to be going through each

one of these in details so let's start

with the first one hooking our setup

there are three main array keys that we

need to be aware of in order to get

things rolling so that our paragraphs

pre-process as expected and the first is

bass book second is the variables that

we want to create and finally the path

where our template lives so inside a

book theme this is what it would look

like for a paragraph that we defined as

food first we have a Facebook we're

sending in a paragraph we have a few

variables that we're defining and

finally our path now let's dive even

deeper and kind of go through each one

of these piece by piece and the first

one is bass look so bass books these are

defined in another modules hook theme so

like node has a bass hook taxonomy terms

have a bass book with the paragraphs

module we have to make sure we define

the bass book as paragraph so that it

knows to override and extend the

paragraph bass hook with the custom

modules that we are sorry and so with

the custom variables that we are

creating in our custom module so let's

take a look at those variables now

variables this is just an array of

custom variables and their default value

so we're defining here header with a

default value of null and text with a

default value of null and finally our

path this is where our paragraphs custom

template lives now dollar sign path this

variable it's a it's in hook theme so

all that we're doing here is just

concatenating from our modules root

directory so all the templates live in

chromatic underscore paragraphs slash

templates slash paragraph this is just

for organizational sake

now next in the story of how do we

process is the bulk of it handled by our

preprocessor class so in the sample repo

and then our custom module we have

source / paragraph preprocessor dot PHP

this is just setting up a class to

handle all of the sort of programming

and functionality that we want to have

within our preprocessor now within this

we are going to be defining custom

methods which are just functions that

are available to us that we're going to

be creating to do the actual

pre-processing so we're setting up a

preprocessor class here and inside of it

we have a process method defined it as

pre processed food we're gonna see what

this looks like in the actual module in

a second but we're just going to talk

through what this actually does so its

most basic date level all we're doing is

retrieving the data from our paragraph

that we set up in the config and install

and then we're going to be returning

specific variables that we defined

earlier header and text that are

referenced in the render array that we

defined earlier in the hook theme so

further down on our module we have our

class and right below that is our custom

pre process foo method now I'm defining

here at the top content because cuffin

is essentially what we're going to be

looking for for our fields there's a lot

of data in variables that's available to

us this kind of just narrows it down so

that we can essentially follow the same

recipe of content and passing the field

machine name and getting the field

values this way so here we're defining

our variables its header and text like

we're in our hook theme and below that

in comments is what it would look like

when we out put it in our twig template

so let's take a look at that twig

template here we have paragraph - - food

HTML that twig and all it's doing is

just we have our own customizations we

have a div we have our header and we

have our text so we're pulling in that

data that we had in our

processor and we have specific variables

that we can go through and assign in

here so we have full control over over

how we want our template files to look

and kind of variables that are inside of

it in the sample repo there's some more

comments at the top about what's defined

and that sort of thing if you want to

step through it so this kind of is like

the steps of going through and what we

look like to pre-process from our hook

theme to our class to our methods to

then finally our template but there's a

bit of optimization so you can imagine

when you're creating your site you have

a site with you know dozens of different

types of paragraphs we want to avoid

having to do a bunch of copy and paste

since it's like is this same process for

each paragraph is what we're following

with our pre-processing recipe so we're

gonna help optimize that by creating our

first service so in the services ie

animal we're just going to do two things

create our service chromatic paragraphs

paragraphs pre-process and we're going

to call the class that we've been

working with in this presentation today

we're just gonna call paragraph

pre-process which allows us to have

access to the methods that exist on that

class now it looks like this inside of

the text editor we just have services or

chromatic paragraphs and then defining

our class so then now that we have all

of this like how does it finally link up

in our module in our module file we need

to make sure that we call template

pre-process paragraph the type the name

of our paragraph this is the machine

name underscore - slash prove in this

case so this might look different than

what you might be familiar with with

some custom modules like why are we

doing like chromatic paragraphs

underscore pre-process paragraph that

sort of naming convention it's because

we're calling template because template

is a very specific word that will

prepare the variables for our paragraph

template so this was frustration when I

was working through this the first time

when I was trying to pre-process in

paragraphs like why was this not working

it's not super clearly defined in the

documentation in the API but it's

something that's critical that we need

to remember when we're trying to pare

pre-process our paragraphs and this is

going to be this is what it looks like

in the text editor so at the top I've

done a few things first I've defined a

constant so this is something that will

be available to us throughout without

having to like copy and paste is just a

preference of mine in our template

pre-processed paragraph through we are

calling our custom service and it's

going to prepare our variables and

return them with our method that exists

on the class so diving a bit deeper

we're going to talk really quickly about

nested entities so when you have a field

that is calling another entity so you

have a paragraph field that calls a

different kind of node you want to get

field values on that how do we do that

it's two steps first you just load that

entity and then you return the values

now this slide is going to be a bit

small just because of how wide

everything is so it just adds up I'll

define it pretty so at the top we're

just checking to see with that our field

has a value so we have a field another

node is our machine name we're just

checking to make sure that we have a

node reference in there before we do

anything and then stepping down if that

field exists we're going to return the

field header value for the entity

reference and below that in comments is

what our twig what it would look like

output it into a template

so putting it all together let's kind of

go through the steps again so each one

of these we have a paragraph type you

make sure it's defined in the hook theme

and the second one is very important but

we only necessarily just need to do it

once since we're working with paragraphs

is just defining a class that all the

methods live in and each method

essentially is a function and then step

three for each paragraph type we make

sure each one has a corresponding method

we do the actual pre-processing and step

four the result of our hard work each

paragraph type has a tweak template as

an outcome so a quick use case like what

is the ideal use case for pre-processing

paragraphs and I come across the first

one is component libraries now this

component library for now-familiar is a

front-end developer will create like

HTML markup and CSS that matches to what

you want to develop in your CMS and it's

fully defined for you and so with

pre-processing you can just match the

markup and like plugging your values

where you need them to be so for example

here we have a block quote and where

there are certain components in each

block posts we have a citation a source

and attribution now we can define these

fields in a paragraph and with our P

processing define specific variables to

represent each field and just kind of

plug and play with the twig template

into the citation for the block quote

into where the P tag is like that's

where the content would live and then

the by Neil Stevenson would be like

where the attribution field would live

as well now with a component library

like the CSS and JavaScript is usually

all prepared so you can kind of just

like you copy and paste like you mimic

that and you pulling your values that's

what we're trying to do here another

example is an audio paragraph so that we

can have a link to the source where the

audio source lives

we'll have a label for for this and then

also a description so there's a lot of

power in paragraphs because you can

essentially like see your site as

components if you're working with a

front-end developer they can create

these components and you can like

translate them to your twig templates do

your pre-processing set up your

configuration for your paragraph fields

and like plug in the values this helps

us a lot with velocity in terms of you

know just creating things and this is

like my own personal experience with

clients in the past of how we've gone

through the process of them creating

components I translate them into Drupal

into paragraphs they come up with new

components we do the same process again

and again so when it all goes wrong when

things like you follow this process the

things still aren't linking up we debug

so - debugging tools that I want to give

a shout out to the first one is a module

Twigg VAR dumper now this is for

debugging on the front-end so if you

have a twig template and you want to see

what's inside of a variable you can use

twig bar jumper to call call a debugging

function to see what exists in there and

then by default we have a symphony

component var dump earth which plea

bargain for uses this is a back end

debugging so when you're pre-processing

file you you'll be able to call this to

like see that before it gets to the

front end and the template and finally

when you're running out of memory this

is a trick from Morton that I've used a

ton of times this will return all

available values within a template

within the context so you can see like

all of the different keys and variables

that you have available to you inside of

a template and from there do further

debugging so this is it if you're trying

to call those other debugging functions

they don't work this usually where it's

almost on your side of time so we have a

few minutes for some question and

answers but real quick tomorrow I'll get

involved there's a contribution day

senator you don't have to know how to

code in a June highlight from canopy is

going to be doing the training at the

end I'm going to have

my session review here I'll go through

and reload my slides to make sure that

the github that link references the

right page there so get that debug but

yeah that's pre-processing paragraphs

you have some time for questions so

thank you very much yes yes so the

question is what were the benefits of

the two modules so var dumper both that

all of these debugging things are

available to us in Drupal these kind of

extract it so there's an easier way

bargain burner makes it easier to debug

in the front-end in your tweak templates

specifically and var dumper is a

symphony component I found it more

reliable than using Kent or the devel

module and it's available to us as well

so those are two heads up you don't need

to really do much to get it far number

up and running with I believe it's

automatically included now so you should

be able to access it there's a link to

like the documentation on the slide of

how do you do that yes so in this case

this is all done within a module and on

most sites where you're doing the bean

with components that are not really

redistributed well beyond that site how

would you change this if you were doing

it in the theme instead of module

yeah that's a excellent question so the

questions we covered today doing this in

a module how would we do this within a

theme essentially this the same steps

would exist what we're doing with

creating a class and creating methods

within that class would all exist within

your hook theme if you want or you can

create a class in a similar sort of

structure now this is kind of

opinionated in the way that I've done it

based off of client experience we

created it in the module instead of a

theme because there are multiple sites

in separate themes but wanting to use

the same components so if you're in a

theme you'd have the same hook theme you

you know defy you you can cut out some

of the things like the services and you

could just call those template

underscore tree process functions and

inside of there you can do your

pre-processing without having like look

to an external class yeah yeah yeah sure

what's what value does the service

provide like why why make the class in

the first place so another good part oh

sorry

so why make the class in the first place

what does the service component from

providing this this is like also this

whole presentation is like contains with

my own programming opinions and I just

like having things separated out so that

in the module file unit calling separate

classes that are doing different things

so everything within the paragraph

preprocessor and this was you know

working with different people across the

team it was like a paradigm so that

everyone knew that if you're doing any

sort of pre-processing it exists in that

class if we're doing anything external

to it it exists somewhere else and it's

defined differently so it was kind of

just to make sure that you know dents

that were being on-boarded or people

that are inherent in the site know

exactly where to look for pre-processing

instead of having it all with him like

the dot module file or creating a large

module file map because it could exist

there but it's just like making it a bit

easier to find later on

any other questions thoughts

cool night um yeah follow me come talk

to me afterwards

was there a question to this hot temper

what is the service

Oh

so what does the service do essentially

allows us to be able to call that class

anywhere so you have it easily

accessible to us

thank you yeah oh yeah so if anyone has

any questions or some things were like a

bit over your head we can you know step

through some of these things I know that

classes methods be processing it's a lot

especially if you're new into Drupal or

PHP so feel free to reach out to me

follow me in you know

just find me and we can chat after it

but yeah that's my time thanks so much

[Applause]

Captions made possible by ClarityPartners.com. Chicago area Drupal consultants