Demystifying the Craft API for Twig Developers

Craft ships with a powerful and diverse API for doing all kinds of handy things. Helper functions, advanced database querying, input validators, content migrations, data caches, and much more. In this talk we will look at real world use cases to leverage the full suite of Craft features available to a Twig developer, as well as learn how to wade through the reference docs and discover more useful functionality on your own.

Originally presented at Dot All 2023.

Transcript

1. Demystifying the Cra API (for Twig developers)
2. ¡Hola! I’m Prateek !
4. Sheets to Tables Contact Form Tuner Cryptographer Router Obfuscator
6. Why When How
7. Why bother using the API
8. Once upon a time… There was a web developer
9. Started building sites… using Cra CMS
10. craft.entries craft.categories craft.users To the developer, templates meant {% for %} {% set %} {% block %}
11. craft.entries craft.categories craft.users But over time realised… {% for %} {% set %} {% block %}
12. Could use more than just… Element Queries Twig Tags
13. Twig Functions Could use more than just… Element Queries Twig Tags Twig Filters
14. Twig Functions Cra Helpers Cra Components Yii Framework Composer Packages PHP
15. And the developer’s templates became be er, faster, stronger!
16. fin
17. This developer was none other than me "
18. API* Element Queries Twig Tags Twig Filters Twig Functions Cra Helpers Cra Components Yii Framework Composer Packages PHP
19. Recreate the templating journey for loops & cra .entries # Haz API
20. Site for a “Dot All” Music Festival
21. (Send in petitions to Leah)
28. 3 content types 1. Artists 2. Tickets 3. Performances
29. Template
30. Query Entries
31. Loop & Render
32. Artists Tickets Types Performances
33. Should be quite familiar to anyone who's built a Cra site
34. Okay, back to the “Why” Benefits I’ve experienced using the API
35. Readability
36. example 1 of 1
37. <span class="text-xs {{ seatsAvailable < 10 ? 'text-red-500' }} {{ seatsAvailable >= 10 and seatsAvailable <= 50 ? 'text- amber-500' }} {{ seatsAvailable > 50 ? 'text-green-500' }}"> {{ seatsAvailable }} seats </span>
38. Using tag() {{ tag('span', { class: [ 'text-xs', seatsAvailable < 10 ? 'text-red-500', seatsAvailable >= 10 and seatsAvailable <= 50 ? 't…', seatsAvailable > 50 ? 'text-green-500', ], text: seatsAvailable ~ ' seats', }) }}
39. <span class="text-xs {{ seatsAvailable < 10 ? 'text-red-500' }} {{ seatsAvailable >= 10 and seatsAvailable <= 50 ? 'text- amber-500' }} {{ seatsAvailable > 50 ? 'text-green-500' }}"> {{ seatsAvailable }} seats </span> {{ tag('span', { class: [ 'text-xs', seatsAvailable < 10 ? 'text-red-500', seatsAvailable >= 10 and seatsAvailable <= 50 ? 'text…', seatsAvailable > 50 ? 'text-green-500', ], text: seatsAvailable ~ ' seats', }) }} More Readable
40. HTML A ributes as key-value pairs | attr({ … }) attr({ … }) tag('a', { … }) ul(list, { … }) ol(list, { … }) input('tel', 'p', { … }) {% tag 'a' with { … } %}
41. Readable :: Easier to understand
42. Readable :: Easier to understand collaborate maintain spot bugs
43. Developer Efficiency
44. example 1 of 2
45. {% set eventsList = craft.entries .section('events') .orderBy('startDate') .all() %} {% set eventsList = craft.entries .section('events') .orderBy('startDate') .all() %}
46. {% set eventsList = craft.entries .section('events') .orderBy('startDate') .all() %}
47. {% set eventsList = craft.entries .section('events') .all() |sort((a, b) => a.startDate == b.startDate ? a.venue.one().title <=> b.venue.one().title : a.startDate <=> b.startDate ) %}
48. {% set eventsList = craft.entries .section('events') .all() |sort((a, b) => a.startDate == b.startDate ? a.venue.one().title <=> b.venue.one().title : a.startDate <=> b.startDate ) %}
49. {% set eventsList = craft.entries .section('events') .all() |multisort([ 'startDate', 'venue.0.title', ]) %}
50. {% set eventsList = craft.entries .section('events') .all() |sort((a, b) => a.startDate == b.startDate ? a.venue.one().title <=> b.venue.one().title : a.startDate <=> b.startDate ) %} {% set eventsList = craft.entries .section('events') .all() |multisort([ 'startDate', 'venue.0.title', ]) %} Less mental math
51. example 2 of 2
52. Truncate to avoid crazy big pop-ups
53. How many of you have wri en your own truncation code? $ Guilty
54. {% macro truncate(string, chars = -1) %} {% set string = string | trim %} {% if truncate > 0 and string|length > truncate %} {% set string = string|slice(0, truncate) ~ '…' %} {% endif %} {{- string -}} {% endmacro %} ⚠ Bug: Partially Splits Words
55. {% macro truncate(string, maxLength) %} {% set words = string|split(' ') %} {% set truncatedString = '' %} {% for word in words %} {% set newString = truncatedString ~ ' ' ~ word %} {% if newString|length < maxLength %} {% set truncatedString = newString %} {% endif %} {% endfor %} {{ (truncatedString ~ '...')|trim }} {% endmacro %} ⚠ Bug: Can Skip Long Words
56. {% macro truncate(content, words = 50, truncator = '...') %} {% set symbols = content | striptags | split(" ") %} {% set content = (symbols|length <= words) ? ( symbols | join(" ") | replace("\t", '') ) : ( symbols | slice(0, words) | join(" ") | replace("\t", '') ~ (truncator ? '&nbsp;' ~ truncator : '' ) ) %} {{ content|replace('&nbsp;', '') }} {% endmacro %} ⚠ Bug: Might double escape
57. {{ artist.bio | truncate(200) }} It Just Works™
58. {{ artist.bio | truncate(200) }} & Made me feel stupid It Just Works™
59. I trust P&T code over mine any day '
60. Use system lib :: Less custom logic
61. Use system lib :: Less custom logic Less mental math Fewer bugs Ship faster Widely deployed Future proof Less code More robust
62. Superpowers
63. example 1 of 2
64. {{ artist.bio | replace( artist.title, tag('strong', { text: artist.title, class: 'text-base font-semibold', }) ) }}
65. {{ artist.bio | replace( artist.title, tag('strong', { text: artist.title, class: 'text-base font-semibold', }) ) }}
66. {{ create('craft\\helpers\\StringHelper') .replaceFirst( artist.bio, artist.title, tag('strong', { text: artist.title, class: 'text-base font-semibo…', }) ) }}
67. {{ create('craft\\helpers\\StringHelper') .replaceFirst( artist.bio, artist.title, tag('strong', { text: artist.title, class: 'text-base font-semibo…', }) ) }} Free Boost
68. create() :: Cra & Yii Helpers
69. create() :: Cra & Yii Helpers Array Helper HTML Helper JSON Helper String Helper DateTime Helper URL Helper
70. example 2 of 2
71. Pull in missing artist bios from Wikipedia
72. Wikipedia provides an API with JSON responses
73. {% set response = create('GuzzleHttp\\Client') .get( 'https://en.wikipedia.org/api/rest…', { headers: { accept: 'application/json', charset: 'utf-8', }, }) %} {% if response.getStatusCode() == 200 %} {% set response = apiResponse .getBody() .getContents() | json_decode
74. accept: 'application/json', charset: 'utf-8', }, }) %} {% if response.getStatusCode() == 200 %} {% set response = apiResponse .getBody() .getContents() | json_decode %} {{ response.description }} {{ response.extract_html }} {% endif %}
75. {% set response = create('GuzzleHttp\\Client') .get( 'https://en.wikipedia.org/api/rest…', { headers: { accept: 'application/json', charset: 'utf-8', }, }) %} Immensely Powerful {% if response.getStatusCode() == 200 %} {% set response = apiResponse .getBody() .getContents() | json_decode %} {{ response.description }} {{ response.extract_html }} {% endif %}
76. create() :: Composer Packages
77. create() :: Composer Packages any PHP class Guzzle Stringy Cookie
78. Performance
79. example 1 of 2
80. Wikipedia API calls need to be cached
81. Cra has a Cache component
82. cra .app.cache
83. {# Store #} {% craft.app.cache.set(cacheKey, value) %} {# Re-use #} {% set value = craft.app.cache.get(cacheKey) %}
84. {% set cacheKey = [url, params] %} {% set response = craft.app.cache.get(cacheKey) %} {% if response is same as(false) %} {# Make API call #} {% set response = ... %} {# Cache response #} {% do craft.app.cache.set(cacheKey, response) %} {% endif %}
85. Fetch once, Store & Re-use 20x(
86. craft.app.Components & Services
87. craft.app.Components & Services Fields Globals Session Request Config Site Sections
88. example 2 of 2
89. Reduce Database queries
90. {% set eventsList = craft.entries .section('events') .orderBy('startDate') .all() %} {% for event in eventsList %} {{ event.title }} {{ event.artists.all()|join }} {{ event.venue.one() }} {{ event.ticketTypes.all()|join }} {% endfor %}
91. {% set eventsList = craft.entries .section('events') .orderBy('startDate') .all() %} {% for event in eventsList %} {{ event.title }} {{ event.artists.all()|join }} {{ event.venue.one() }} {{ event.ticketTypes.all()|join }} {% endfor %}
92. {% set eventsList = craft.entries .section('events') .orderBy('startDate') .with(['artists', 'venue', 'ticketTypes']) .all() %} {% for event in eventsList %} {{ event.title }} {{ event.artists.all()|join }} {{ event.venue.one() }} {{ event.ticketTypes.all()|join }} {% endfor %}
93. {% set eventsList = craft.entries .section('events') .orderBy('startDate') .with(['artists', 'venue', 'ticketTypes']) .all() %} {% for event in eventsList %} {{ event.title }} {{ event.artists.all()|join }} {{ event.venue.one() }} {{ event.ticketTypes.all()|join }} {% endfor %} 3x(
94. Eager-load all the element fields in a loop
95. Recap Better readability Easier to maintain More future proof Fewer bugs Write lesser code Ship faster Improved performance Robustness Free system features “Superpowers”
96. When to use the API
97. Along your templating journey…
98. Ask yourself if the feature you’re developing is…
99. …common across other websites? • Truncation • Sorting • Filtering
100. …present in the Cra Control Panel? • Caching • Validations • External API requests
101. …not unique to the context of websites? • Math • Date & Time • Formatting • Encoding / decoding
102. If the answer is “Yes” The API has (probably) solved it already
103. As projects grew in complexity… Pa erns started to emerge
104. Fetch Content
105. Fetch Cra Elements — Entries, MatrixBlocks, Categories, Users… URL & Route Variables External Sources
106. Fetch Content Transform Content
107. Transform Match a certain structure or format Apply biz logic Combine various sources
108. Fetch Content Transform Content Render Content
109. Render HTML tags & attributes Images, media, assets Content styling
110. Fetch Content Transform Content Render Content
111. How to use the API
112. Small workflow changes
113. Pause and reflect
114. Pause and reflect Look for the Patterns
115. Advanced DB queries Eager-loading Caching External API call Fetching Content Patterns
116. Transforming Content | multisort | map | filter | reduce Collections | merge Patterns
117. Rendering Content | attr() | truncate StringHelper .replaceFirst() svg() url() Patterns
118. Pause and reflect Look for the Patterns Answer the Prompts
119. For common web features Twig Filters Twig Functions Cra Helpers
120. For features in the Cra Control Panel Cra Components Yii Framework Cra Helpers
121. For features not unique to websites Cra Helpers Cra Components Yii Framework Composer Packages PHP
122. Pause and reflect Search the API
123. Search the API Embrace the docs
124. Use pinned tabs to keep them handy
125. Search, dig deep, repeat — docs are updated constantly
126. Zoom into specifics in the Class Reference
127. Pause and reflect Search the API Experiment, familiarise
128. Experiment, familiarise Explore quickly, freely, and without worry
129. templates/test.twig For quick trials and experiments of whatever you spot in the docs
130. Use version control to easily roll back any change
131. ./cra db/backup If you’re ever concerned about damaging your content
132. Pause and reflect Search the API Experiment, familiarise
133. Docs may not be your starting point
134. Alternate Entry Point Manipulating Lists
135. We’re o en working with lists Arrays Lists of entries Key-value pairs Nested arrays
136. Tools for manipulating lists | map | filter | reduce | sort | multisort | column | unique
137. Bunch of them take “arrow functions” |map(n => n * 2) |filter(n => n > 20) |sort((a,b) => a<=>b)
138. example
140. {% set artistsList = craft.entries .section('artists') .orderBy('title asc') .relatedTo(eventsList) .all() %}
142. {% set eventsList = craft.entries .section('events') .with(['venue', 'ticketTypes', 'artists']) .all() %}
143. {% set artistsList = eventsList |map(event => event.artists.all()) %}
144. {% set artistsList = eventsList |column('artists') %}
145. {% set artistsList = eventsList |column('artists') |reduce((flatList, artists) => flatList|merge(artists), []) |unique |multisort('title') %}
146. Even more succinct using Laravel Collections
147. {% set artistsList = collect(eventsList) .pluck('artists') .flatten() .unique() .sortBy('title') .all() %}
148. create()
149. Wrapping Up
150. Why Better readability Easier to maintain More future proof Fewer bugs Write lesser code Ship faster Improved performance Robustness Free system features “Superpowers”
151. When Ask yourself, is it: …common across other websites? …present in the Cra Control Panel? …not unique to the context of websites?
152. When Identify the patterns: Fetching Content Transforming Content Rendering Content
153. How Small workflow changes Pause & reflect Search the docs Experiment, familiarise
154. ✈ ) + , - . / 0 1
155. As a tourist, mostly ge ing by using English & a translator app Navigating the way, visiting sites, taking in experiences
156. However, a resident needs to pickup the local language Adopting local culture, making connections, feeling at home
157. For developers, each technology is like a different country APIs are the local language
158. What would you like to be…
159. …a tourist or a resident?
160. Recall the templating journey? for loops & cra .entries # Haz API
161. for loops & cra .entries # Haz API Tourist Resident
162. for loops & cra .entries # Haz API Tourist Resident Fear, Uncertainty, Doubt Discover, Try, Thrive
163. Gracias 2 github.com/miranj/demystifying-cra -api