HTML, Strings & Text
Generate HTML and operate on text (strings or longer-form).
The top layer of Summit is the presentation layer, powered by the use of Text
blocks that can be used to compose large swaths of text for use as HTML, prompts, and more.
Text
Because they generate presentation (content), Text
blocks are often the second to the last step of a model, pulling everything together to compose a response.
Liquid syntax
Liquid is a common templating language, and Summit bundle's the Django implementation of it into almost every block. Text
is a natural place to take advantage of this, since composing HTML elements using loops and variables is much easier than crafting by hand.
Here's a simple example of using liquid in a text block:
=Text(""" {{ "moby dick" | upper }} """)
Would generate the value: MOBY DICK
.
Most powerfully, you can refer to the value of other events on the canvas by using their titles. If you had a String
event like so:
=String("whale of a tale")
And its title was draft_book_name
, then you could use that string in your Text
block:
=Text(""" I am thinking of writing a book. Its title is {{ draft_book_name | uppr }}, but this is just a working title. I'm hoping to think of something better. """)
Then this will insert WHALE OF A TALE
into the sentence.
Events that return arrays, lists, or objects will also be treated as such inside of your Text
block.
Variable Naming Rules
Since liquid syntax forbids the use of spaces, special characters, or starting with numbers for variable names, any events you wish you use inside a liquid syntax portion of a
Text
event must conform to this standard. We recommend usinglowercase_event_titles_with_underscores_for_spaces
in this case.
Using Text
inside Text
Text
inside Text
You may also wish to insert or use the rendered contents of a Text
event inside a separate Text
event.
This is perfectly fine; simply use the title to refer to it like any other event:
=Text(""" This text event uses the contents of another text event. You can read it here: {{ my_other_text_event }}.""")
However, you must make sure that the event you wish to insert (ex. my_other_text_event
) is evaluated first. You can do this (and avoid what's known as a "race condition") by using a route to draw an arrow from the first text event to the second. This ensures that the second text event will not render until after the first has finished.
The full catalog of filters and tags
To learn about the tags and filters available through Summit's templating engine, please refer to Django's official template filters and tags documentation.
Some tags, such as
static
, are not supported in the Summit context, as these are intended to work directly with server settings.
Additional custom tags
Summit also provides a growing list of custom tags:
Tag Name | Description | Example |
---|---|---|
fake | Generates fake text. | {% fake 'street_name' %} |
surl | Generates a URL for a Summit model. | {% surl 'my-model' %} |
A full list of fake
providers (like 'street_name'
) can be found in Faker's documentation.
Response options
When you generate text, you'll want to send it somewhere. If that somewhere is part of a JSON object, you can bundle it into an Object:
=Object({"attribute": "{{ my_text_event_title }}"})
If you want to send it to the Playground view, you can send it to the __html
attribute of a Response.
Lastly, if you want to make your model to return HTML as its content-type, you can send it to a response that declares its type as "html"
:
=Response("html")
Any requests to the HTML view of your model will then return this HTML.
String
You can declare a String
in SEL by writing:
=String("Hollow World ...")
A string event will report its value in the ledger as the length of its contents. In the above example, this would be 16
.
Certain event types know how to handle strings.
Matches (Regular Expressions)
Perhaps you'd like to see if a string contains a certain expression, but you don't know for sure what the substring will look like. To do that, SEL provides the Matches
event. The only argument to the Matches
event type is a regular expression, or regex for short.
We can use this event type like so:
=Matches("\d")
This will check to see if a String
contains a digit.
Matches
returns the matches it finds as a list, which can then be used by other downstream events. Matches
will report the number of matches in the ledger.
In addition to searching for matches inside String
events, the Matches
event will also search for matches inside lists of strings, such as those returned by the Parser event.
The World of Regular Expressions
Summit uses the Python
re
module to perform regular expression matches.Regexes are endlessly powerful and complex! Learning them is far beyond the scope of this documentation, but if you can learn the spells of regex, you will be a powerful SEL wizard indeed.
Updated about 1 month ago