What is Strapify?
Strapify is a script that implements common functionality for the population of websites with Strapi CMS data, abstracting it all away into simple to use HTML data attributes.
Straight out of the box, Strapify provides the following functionality:
- Dynamic content - Strapify will automatically populate your website with content from your Strapi CMS.
- Sorting, Filtering, and Pagination - Strapify will automatically sort, filter, and paginate your content based on the attributes you specify. Control attributes enable static buttons to be used to sort, filter, and paginate your content.
- Images and Videos - Strapify makes it easy to render images and videos from your Strapi CMS.
- Rich Text Rendering - Strapify makes it easy to render rich text content from your Strapi CMS.
- Form Submissions - Strapify integrates with the Strapi EZForms plugin, allowing you to easily submit forms to your Strapi CMS.
- Authentication - Basic authentication is supported out of the box, allowing you to restrict access to your content based on user roles.
- JavaScript Hooks - Strapify emits a number of JavaScript events that allow you to easily extend its functionality. Strapify attributes can be modified at runtime to dynamically change the content that is rendered.
- CSS Modifiers - Strapify provides a number of CSS modifiers that allow you to easily style your collection's entries depending on it's content.
The goal of the Strapify project is to enable the integration of a free open source CMS (Strapi) into an otherwise static website, without requiring additional code or otherwise complicating the development process. To this end, we seek compatibility and convenience for both manually built sites and those built with no-code website builders.
Please note that Strapify is not affiliated with Strapi in any way. Strapify is a separate open-source project that aims to make it easier to integrate Strapi into your website.
Getting Started
To start using Strapify, you'll need a running Strapi application. You can create a new one using the Quick Start Guide or use an existing one. Strapify is compatible with Strapi v4 only.
First, you'll need to include the Strapify script in your HTML document. You can do this by downloading the script and hosting it yourself, or by using the CDN version.
Downloading the Script
⬇️ Download
Using the CDN
Paste the following code in the <head> of your HTML document.
<script
src="https://strapify.s3.amazonaws.com/strapify-v0.0.7.js"
data-strapi-api-url="ENTER YOUR STRAPI URL HERE"
type="text/javascript"
></script>
Testing the Script
Once you've included the script, you can test it by opening the console in your browser. You should see a message that says "Strapify running" and "Strapify finished".
Connect to your first collection
To connect to your first collection, you'll need to create a new HTML element with the strapi-collection attribute. The value of this attribute should be the name of the collection you want to connect to. For example, if you have a collection called "articles", you would use the following code:
<div strapi-collection="articles"></div>
Creating your template
To display your collection, you'll need to create another HTML element inside your collection with the strapi-template attribute. Your template element should contain the HTML you want to display for each item in your collection. If you've connected to your collection properly, the template should be repeated for each item in the collection.
<div strapi-collection="articles">
<div strapi-template>
some html to display for each article
</div>
</div>
Using fields in your template
To display the data from your collection, you can use the strapi-field attribute. The value of this attribute should be the name of the field you want to display. For example, if you have a field called "title", you would use the following code:
<div strapi-collection="articles">
<div strapi-template>
<h1 strapi-field="title"></h1>
</div>
</div>
Fields can be linked to many types of HTML elements. For example, you can use the src attribute to display an image:
<div strapi-collection="articles">
<div strapi-template>
<h1 strapi-field="title"></h1>
<img strapi-field="featureImage" />
</div>
</div>
A full list of supported field types can be found here.
Quick Install
⬇️ Download
Quick Install (CDN)
Paste the following code in the <head> of your HTML document.
<script
src="https://strapify.s3.amazonaws.com/strapify-v0.0.7.js"
data-strapi-api-url="ENTER YOUR STRAPI URL HERE"
type="text/javascript"
></script>
Field Elements
Field elements are HTML elements that will have their content modified with data from Strapi when Strapify executes. Each of these elements correspond to a particular field in a Strapi collection. These elements are defined with the strapi-field attribute. How and which content of the field elements are modified is contextual and depends on the element tag and the strapi field type being used. Read through the attribute syntax for more details.
Allowed Attributes:
strapi-field strapi-into strapi-class-add strapi-class-replace strapi-class-conditional
strapi-field
The strapi-field attribute specifies that the element is a field element. Elements with strapi-field will have their content replaced with content from Strapi. How and which content of the field elements are modified is contextual and depends on the element tag and the strapi field type being used.
Below is the HTML to render a collection Person (plural people), with several different element types to render Strapi fields.
<div strapi-collection="people">
<div strapi-template="">
<p strapi-field="name">name</p>
<p strapi-field="age">age</p>
<p>is employed: <span strapi-field="is_employed">is_employed</span></p>
<div strapi-field="bio">
<p>rich text placeholder ( I get deleted ) )</p>
</div>
<img strapi-field="portrait" />
</div>
</div>
| Strapi Field Type | HTML Elements | Comments |
|---|---|---|
| Text | p h span div | The div is typically invalid but can be used as a special case to embed a video. For it to work, your text field must contain a link and the div must contain an iframe child element. |
p h span | Field data will be inserted as text content. | |
| Rich Text | div | HTML elements will be created in the div to render the rich text. |
| Number | p h span | Field data will be inserted as text content. |
| Enumeration | p h span | Field data will be inserted as text content. |
| Date | p h span | Field data will be inserted as text content. |
| Media (Image) | img | The image source will be set to point to the Strapi url for the image. |
| Media (Video) | div | A video element will be inserted into the div. |
| Boolean | p h span | Field data will be inserted as text content. |
For relations see strapi-relation, for repeatable components or multiple media type fields see strapi-repeatable.
Field elements must be a child of a template element or be a template element.
Allowed Elements:
div p h span img
Related Attributes:
Allows Multiple Arguments: 🚫 NO
Examples
<p>Name: <span strapi-field="name">name</span></p>
Renders the value in the Strapi field name.
<img strapi-field="portrait_image">
Renders the image held in the Strapi field portrait_image.
<p>First Name: <span strapi-field="name.first">first name</span></p>
Renders the field first in the component field name.
strapi-into
The strapi-into attribute is used to pass data from a Strapi field directly into an HTML attribute. Elements with this attribute must belong to a template element.
Below is the HTML to render a collection Person (plural people), with a strapi-into attribute to set the alt text of the img to the value held in the Strapi field alt_text.
<div strapi-collection="people">
<div strapi-template="">
<img strapi-field="portrait" strapi-into="alt_text -> alt" />
</div>
</div>
Allowed Elements:
Any.
Related Attributes:
Allows Multiple Arguments: ✅ YES
Examples
<img strapi-into="alt_text -> alt">
Sets the alt attribute of the img element to the value in the strapi field alt_text.
<img strapi-into="image.alt_text -> alt">
Sets the alt attribute of the img element to the value in the field alt_text belonging to the component in the field image.
<img strapi-into="element_id -> id | alt_text -> alt">
Sets the id of the img element to the value in the Strapi field element_id and sets the alt attribute of the img element to the value in the strapi field alt_text.
Template Elements
Template elements are HTML elements that will be duplicated for each entry in a Strapi collection, relation or repeatable field (components, media, etc…).
These elements contain field elements, and are descendants of collection elements, relation elements or repeatable elements. Template elements are defined with the strapi-template attribute.
Multiple templates can be created and chosen dynamically based on the data in Strapi using strapi-template-conditional
Template elements also add a strapi-template-id attribute which can be used in cases where you need to fetch data directly from the Strapi API.
Attributes
strapi-template, strapi-template-conditional
strapi-template
The strapi-template attribute specifies that the element is a template element. All template elements will be removed from the DOM when Strapify runs and replaced with template elements injected with Strapi data. Template elements must exist as children of collection elements, relation elements or repeatable elements. If multiple template elements exist as children to a collection element, relation element or repeatable element, the first occurring template element will be used.
If a collection element, relation element or repeatable element contains a standard template in addition to conditional template elements, any Strapi entries that don’t meet the conditions for any of the conditional templates, will use the standard template as a fallback.
Below is the HTML to specify a template element for the collection people, with two p elements to render the name and age fields.
<div strapi-collection="people">
<div strapi-template="">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
</div>
</div>
Allowed Elements:
Any element.
Related Attributes:
Allows Multiple Arguments: 🚫 NO
Examples
<div strapi-template="">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
</div>
Mark the div element as a template element for the Strapi collection named my_strapi_collection_name_plural.
strapi-template-conditional
The strapi-template-conditional attribute specifies that the element is a conditional template element. Conditional template elements function identically to standard template elements, but take a conditional expression argument which defines a condition that must be met by the data in a Strapi entry for this template to be used. The Strapify Conditional Expression Arguments section details the conditional expression syntax. This attribute is useful in scenarios for which you want to have multiple templates so that certain entries can be rendered with a different appearance, or with different data displayed. A standard template element should always be included in the parent collection element as a fallback in the cases that the data for an entry in the collection does not pass any of the conditional expressions on the conditional template elements.
Below is the HTML to specify two template elements, which have different styles (from the classes red and green). A standard template is provided as a fallback in the case that none of the conditional templates have their conditions met.
<div strapi-collection="people">
<div class="red" strapi-template-conditional="is_employed == false">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
</div>
<div class="green" strapi-template-conditional="is_employed == true">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
</div>
<div strapi-template="">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
</div>
</div>
Allows Multiple Arguments: 🚫 NO
Examples
strapi-template-conditional="name == 'Paul Dirac'"
The template element will be used in the case the the person’s name is Paul Dirac.
strapi-template-conditional="age < 90"
The template element will be used in the case the the person is less than 90 years old.
strapi-template-conditional="is_employed == false"
The template element will be used in the case the the person is not employed. strapi-template-conditional | name == 'Paul Dirac' && age == 82
strapi-template-conditional="name == 'Paul Dirac' && age == 82"
The template element will be used in the case the the person’s name is Paul Dirac and their age is 82.
strapi-template-conditional="(name == 'Paul Dirac' && age == 82) || is_employed == false"
The template element will be used in the case the the person’s name is Paul Dirac and their age is 82 or if they’re unemployed.
strapi-template-conditional="(name == 'Paul Dirac' && age == 82) || (is_employed == false && score == 3.0)"
The template element will be used in the case the the person’s name is Paul Dirac and their age is 82 or if they’re unemployed and their score is 3.
Collection Elements
Collection elements are HTML elements that contain template elements. These elements correspond to a Strapi collection. These elements will contain all the populated template elements after Strapify executes. These elements are defined with the strapi-collection attribute.
Collection elements can exist inside other collection elements, but not as the children of their template elements.
strapi-collection
The strapi-collection attribute specifies that the element is a collection element. The value of this attribute is the plural API id of a Strapi collection.
Strapify will search the element for a template element or a set of template elements if there are conditional template elements, they will be replicated for each entry in the collection.
If multiple template elements exist as children to the collection element, the first occurring template element will be used. If there are two conditional template elements with equivalent conditions, existing as children to the collection element, the first occurrence will be used. All template elements will be removed from the DOM when Strapify runs (you can have many copies of your template to help visualize how your site will look during development, Strapify will remove them for you). Any elements existing as children to the collection element that is not a template element, will be left untouched (you can put text, links, buttons or other things within collection elements).
If the collection element contains a standard template in addition to conditional template elements, any Strapi entries that don’t meet the conditions for any of the conditional templates will use the standard template.
Below is the HTML to render a collection called Person (people), with the name and age fields to be rendered into p elements.
<div strapi-collection="people">
<div strapi-template="">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
</div>
</div>
Filtering, Sorting, and Pagination
Strapify provides a number of attributes that can be used to filter, sort, and paginate your collections. These attributes are:
- strapi-filter - Filter the collection by a given field.
- strapi-sort - Sort the collection by a given field.
- strapi-page and strapi-page-size - Paginate the collection with a given number of entries per page.
These attributes can be used in conjunction with each other to create complex filtering, sorting, and pagination schemes. For example, you can use strapi-filter to filter a collection by a given field, then use strapi-sort to sort the filtered collection by a different field, and finally use strapi-pagination to paginate the sorted collection.
Additionally, there are a number of attributes that can be used to control the behavior of the filtering, sorting, and pagination attributes. These attributes are:
- strapi-filter-control - Control the behavior of the
strapi-filterattribute. - strapi-sort-control - Control the behavior of the
strapi-sortattribute. - strapi-page-control - Control the behavior of the paginated collection.
Note: These attributes can be used even if the filtering, sorting, and pagination attributes are not used. For example, you can use strapi-filter-control to control the behavior of the strapi-filter attribute even if you are not using the strapi-filter attribute.
strapi-sort
The strapi-sort attribute is used to specify a sort order for the populated template elements in a collection, relation or repeatable element. When multiple arguments are given, the sort is done in the order that the arguments appear.
Strapify will reflect changes to this attribute automatically if it is changed with a script.
The strapi-sort-control attribute can be used on buttons to control the behavior of the strapi-sort attribute when clicked.
Below is the HTML to render a collection called Person (people), sorted by the name field.
<div strapi-collection="people" strapi-sort="name">
<div strapi-template="">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
</div>
</div>
Allows Multiple Arguments: ✅ YES
Examples
<div strapi-collection="people" strapi-sort="name">
The collection people will be sorted by name.
<div strapi-collection="people" strapi-sort="name:asc">
The collection people will be sorted by name.
<div strapi-collection="people" strapi-sort="id">
The collection people will be sorted by Strapi id.
<div strapi-collection="people" strapi-sort="name:desc">
The collection people will be sorted by name, in descending order.
<div strapi-collection="people" strapi-sort="name | age">
The collection people will be sorted by name then age.
<div strapi-collection="people" strapi-sort="name | age | id">
The collection people will be sorted by name then age then id.
<div strapi-collection="people" strapi-sort="qs.fieldName">
The collection people will be sorted by whatever field is stored in the query string parameter fieldName.
<div strapi-collection="people" strapi-sort="[location][city]">
The collection people will be sorted by the value of city in the component field location.
strapi-sort-control
The strapi-sort-control attribute is used on input elements, such as buttons, radio buttons, selects and check boxes. When the input element triggers an event, the value of the attribute will set the value of strapi-sort on the parent collection element, and the collection will be rerendered with the new sort. The value of this attribute will be the new value of strapi-sort on the parent collection when the input event is triggered.
Below is the HTML to filter a collection Person (people), sorted by either first names or age when one of the a elements is clicked.
<div strapi-collection="people">
<a strapi-sort-control="first_name">Filter by name</a>
<a strapi-sort-control="age">Filter by age</a>
<div>
<div strapi-template="">
<p strapi-field="first_name">first name here</p>
<p strapi-field="age">age here</p>
</div>
</div>
</div>
Below is the HTML to filter a collection Person (people), sorted by either first names or age when one of two options in a select is chosen.
<div strapi-collection="people">
<div>
<!-- a form element is not needed here but is necessary to use select elements in webflow -->
<form>
<!-- there are two valid ways to specify the control value for option elements -->
<!-- this way will work with webflow (using value) -->
<select strapi-sort-control="">
<option value="first_name">Paul</option>
<option value="age">Richard</option>
</select>
<!-- this is the second way (using strapi-control-value) -->
<select strapi-sort-control="">
<option strapi-control-value="first_name">Paul</option>
<option strapi-control-value="age">Richard</option>
</select>
</form>
<div strapi-template="">
<p strapi-field="first_name">first name here</p>
<p strapi-field="age">age here</p>
</div>
</div>
</div>
Below is the HTML to filter a collection Person (people), sorted by either first names or age when one of two radio buttons is clicked.
<div strapi-collection="people">
<div>
<!-- a form element is not needed here but is necessary to use radio type input elements in webflow -->
<form>
<!-- there are two valid ways to specify the control value for radio elements -->
<!-- this way will work with webflow (using value) -->
<div strapi-sort-control="">
<label>
<input type="radio" name="radio" value="first_name" /> Paul
</label>
<label> <input type="radio" name="radio" value="age" /> Richard </label>
</div>
<!-- this is the second way (using strapi-control-value) -->
<div strapi-sort-control="">
<label>
<input type="radio" name="radio" strapi-control-value="first_name" />
Paul
</label>
<label>
<input type="radio" name="radio" strapi-control-value="age" /> Richard
</label>
</div>
</form>
<div strapi-template="">
<p strapi-field="first_name">first name here</p>
<p strapi-field="age">age here</p>
</div>
</div>
</div>
Below is the HTML to filter a collection Person (people), sorted by either first names or age depending on whether or not the corresponding checkbox type input elements is selected.
<div strapi-collection="people">
<div>
<!-- a form element is not needed here but is necessary to use checkbox type input elements in webflow -->
<form>
<!-- you must use strapi-control-value for checkboxes -->
<div strapi-sort-control="">
<label>
<input type="checkbox" strapi-control-value="first_name" /> Paul
</label>
<label>
<input type="checkbox" strapi-control-value="age" /> Richard
</label>
</div>
</form>
<div strapi-template="">
<p strapi-field="first_name">first name here</p>
<p strapi-field="age">age here</p>
</div>
</div>
</div>
strapi-filter
The strapi-filter attribute is used to specify a filter for the populated template elements in a collection element. The arguments for this attribute conform to the the Strapi query string API parameter syntax, with the filter= prefix omitted (see examples). This allows for filtering to be done based on the value of the fields within a strapi entry. When multiple arguments are given they must be given a unique index and each must contain a logical operator to conform to the Strapi query string API syntax for filtering.
Strapify will reflect changes to this attribute automatically if it is changed with a script.
Below is the HTML to render a collection called Person (plural people), filtered to only include people with an age of 42, with the name and age fields to be rendered into p elements.
<div strapi-collection="people" strapi-filter="[age][$eq]=42">
<div strapi-template="">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
</div>
</div>
Allows Multiple Arguments: ✅ YES
Examples
<div
strapi-collection="people"
strapi-filter="[name][$eq]=Paul Dirac"
>
The collection people will be filtered to include only people with the name Paul Dirac.
<div
strapi-collection="people"
strapi-filter="[$or][0][name][$eq]=Paul Dirac | [$or][1][name][$eq]=Richard Feynman"
>
The collection people will be filtered to include only people with the name Paul Dirac or Richard Feynman.
<div
strapi-collection="people"
strapi-filter="[$and][0][name][$eq]=Paul Dirac | [$and][1][age][$eq]=82"
>
The collection people will be filtered to include only people with the name Paul Dirac who are of age 82.
<div
strapi-collection="people"
strapi-filter="[$and][0][name][$eq]=Paul Dirac | [$and][1][age][$eq]=82 | [$and][2][name][$eq]=Richard Feynman"
>
The collection people will be filtered to include only people with the name Paul Dirac who are of age 82 and the name Richard Feynman.
<div
strapi-collection="people"
strapi-filter="[qs.fieldName][$eq]=qs.fieldValue"
>
The collection people will be filtered to include only people that meet the condition that the field name, given by the query string variable fieldName is equal to the the value given by the query string variable fieldValue. This is useful for creating dynamic pages that are populated with data from Strapi.
strapi-filter-control
The strapi-filter-control attribute is used on input elements, such as buttons, radio buttons, selects and check boxes. When the input element triggers an event, the value of the attribute will set the value of strapi-filter on the parent collection element, and the collection will be rerendered with the new filter. The value of this attribute will be the new value of strapi-filter on the parent collection when the input event is triggered.
Below is the HTML to filter a collection Person (people), filtered by the first names Paul or Richard when one of two possible a elements is clicked.
<div strapi-collection="people">
<a strapi-filter-control="[first_name][$eq]=Paul">Filter by Paul</a>
<a strapi-filter-control="[first_name][$eq]=Richard">Filter by Richard</a>
<div>
<div strapi-template="">
<p strapi-field="first_name">first name here</p>
<p strapi-field="age">age here</p>
</div>
</div>
</div>
Below is the HTML to filter a collection Person (people), filtered by the first names Paul or Richard when one of two options in a select is chosen.
<div strapi-collection="people">
<div>
<!-- a form element is not needed here but is necessary to use select elements in webflow -->
<form>
<!-- there are two valid ways to specify the control value for option elements -->
<!-- this way will work with webflow (using value) -->
<select strapi-filter-control="">
<option value="[first_name][$eq]=Paul">Paul</option>
<option value="[first_name][$eq]=Richard">Richard</option>
</select>
<!-- this is the second way (using strapi-control-value) -->
<select strapi-filter-control="">
<option strapi-control-value="[first_name][$eq]=Paul">Paul</option>
<option strapi-control-value="[first_name][$eq]=Richard">
Richard
</option>
</select>
</form>
<div strapi-template="">
<p strapi-field="first_name">first name here</p>
<p strapi-field="age">age here</p>
</div>
</div>
</div>
Below is the HTML to filter a collection Person (people), filtered by the first names Paul or Richard when one of two radio buttons is clicked.
<div strapi-collection="people">
<div>
<!-- a form element is not needed here but is necessary to use radio type input elements in webflow -->
<form>
<!-- there are two valid ways to specify the control value for radio elements -->
<!-- this way will work with webflow (using value) -->
<div strapi-filter-control="">
<label>
<input type="radio" name="radio" value="[first_name][$eq]=Paul" />
Paul
</label>
<label>
<input type="radio" name="radio" value="[first_name][$eq]=Richard" />
Richard
</label>
</div>
<!-- this is the second way (using strapi-control-value) -->
<div strapi-filter-control="">
<label>
<input
type="radio"
name="radio"
strapi-control-value="[first_name][$eq]=Paul"
/>
Paul
</label>
<label>
<input
type="radio"
name="radio"
strapi-control-value="[first_name][$eq]=Richard"
/>
Richard
</label>
</div>
</form>
<div strapi-template="">
<p strapi-field="first_name">first name here</p>
<p strapi-field="age">age here</p>
</div>
</div>
</div>
Below is the HTML to filter a collection Person (people), filtered by the first names Paul and/or Richard depending on whether or not the corresponding checkbox type input elements is selected. Since both checkboxes can be selected at once, the logical [$or] Strapi operator is used.
<div strapi-collection="people">
<div>
<!-- a form element is not needed here but is necessary to use checkbox type input elements in webflow -->
<form>
<!-- you must use strapi-control-value for checkboxes -->
<div strapi-filter-control="">
<label>
<input
type="checkbox"
strapi-control-value="[$or][0][first_name][$eq]=Paul"
/>
Paul
</label>
<label>
<input
type="checkbox"
strapi-control-value="[$or][1][first_name][$eq]=Richard"
/>
Richard
</label>
</div>
</form>
<div strapi-template="">
<p strapi-field="first_name">first name here</p>
<p strapi-field="age">age here</p>
</div>
</div>
</div>
strapi-page
The strapi-page attribute is used to specify a which page Strapify will fetch from Strapi. The default value is 1. When an out of bounds page index is given, Strapify will automatically convert it to the nearest valid index.
Strapify will reflect changes to this attribute automatically if it is changed with a script.
Below is the HTML to render the second page of the collection Person (plural people), with the name and age fields to be rendered into p elements.
<div strapi-collection="people" strapi-page="2">
<div strapi-template="">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
</div>
</div>
Allows Multiple Arguments: 🚫 NO
Examples
<div strapi-collection="people" strapi-page="1">
The collection "people" will be rendered with the first page of the collection.
<div strapi-collection="people" strapi-page="2">
The collection "people" will be rendered with the second page of the collection.
strapi-page-size
The strapi-page-size attribute is used to specify the size of pages when data is fetched from Strapi. When unspecified Strapi’s default size will be used (25).
Strapify will reflect changes to this attribute automatically if it is changed with a script.
Below is the HTML to render a collection called Person (plural people), with a page size of 5, with the name and age fields to be rendered into p elements.
<div strapi-collection="people" strapi-page="1" strapi-page-size="5">
<div strapi-template="">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
</div>
</div>
Allows Multiple Arguments: 🚫 NO
Examples
<div strapi-collection="people" strapi-page-size="5">
The collection "people" will be rendered with a page size of 5.
<div strapi-collection="people" strapi-page-size="10">
The collection "people" will be rendered with a page size of 10.
strapi-page-control
The strapi-page-control attribute is used on input elements, such as buttons, radio buttons and selects. This attribute accepts either a number, which will directly set the page of the collection element, or a sign prefixed number which will increment/decrement that page by the number that follows.
Below is the HTML to paginate and render render a collection Person (people), with a button to go to the first page, next page and previous page.
<div strapi-collection="people" strapi-page="1" strapi-page-size="4">
<a strapi-page-control="1">First Page</a>
<a strapi-page-control="+1">Next Page</a>
<a strapi-page-control="-1">Prev Page</a>
<div>
<div strapi-template="">
<p strapi-field="first_name">first name here</p>
<p strapi-field="age">age here</p>
</div>
</div>
</div>
Below is the HTML to paginate and render render a collection Person (people), with a select option for the first four pages.
<div strapi-collection="people">
<div>
<!-- a form element is not optional here -->
<form>
<!-- there are two valid ways to specify the control value for option elements -->
<!-- using value -->
<select strapi-page-control="">
<option value="1">1</option>
<option value="2">2</option>
<option value="3">3</option>
<option value="4">4</option>
</select>
<!-- using strapi-control-value -->
<select strapi-page-control="">
<option strapi-control-value="1">1</option>
<option strapi-control-value="2">2</option>
<option strapi-control-value="3">3</option>
<option strapi-control-value="4">4</option>
</select>
</form>
<div strapi-template="">
<p strapi-field="first_name">first name here</p>
<p strapi-field="age">age here</p>
</div>
</div>
</div>
Below is the HTML to paginate and render render a collection Person (people), with a radio button for the first two pages.
<div strapi-collection="people">
<div>
<!-- a form element is optional here -->
<form>
<!-- there are two valid ways to specify the control value for radio elements -->
<!-- using value -->
<div strapi-page-control="">
<label> <input type="radio" name="radio" value="1" /> Paul </label>
<label> <input type="radio" name="radio" value="2" /> Richard </label>
</div>
<!-- using strapi-control-value -->
<div strapi-page-control="">
<label>
<input type="radio" name="radio" strapi-control-value="1" /> Paul
</label>
<label>
<input type="radio" name="radio" strapi-control-value="2" /> Richard
</label>
</div>
</form>
<div strapi-template="">
<p strapi-field="first_name">first name here</p>
<p strapi-field="age">age here</p>
</div>
</div>
</div>
Allowed Elements:
a button select input type="radio" input type="checkbox"
Allows Multiple Arguments: 🚫 NO
strapi-control-value
The strapi-control-value attribute is used on elements which are children of an element with one of the strapi-filter-control, strapi-sort-control or strapi-page-control attributes. The allows for the use of inputs which exists as multiple elements such as in the case with select/option elements, radio input elements and checkbox input elements. See the sections for strapi-filter-control, strapi-sort-control or strapi-page-control for examples of how to use this attribute.
Relation & Repeatable Elements
Relation & repeatable elements are HTML elements that contain template elements. These elements correspond to a Strapi relation or repeatable field. These elements will contain all the populated template elements after Strapify executes. These elements are defined with the strapi-relation or strapi-repeatable attribute.
strapi-relation
The strapi-relation attribute specifies that the element is a relation element. Relation elements function identically to collection elements, except they are automatically filtered to only retrieve entries in the collection in the relation. Like collection elements, relation elements must contain templates. The field elements in those templates will reference fields existing on entries of the related collection. The argument must provide both the name of the relation field and the name of the collection being related, separated by a comma.
Below is the HTML to render the collection people, which has a relation with itself to define each person’s children. Each child of a person will have their name and age rendered.
<div strapi-collection="people">
<div strapi-template="">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
<div strapi-relation="children, people">
<div strapi-template="">
<p strapi-field="name">child name goes here</p>
<p strapi-field="age">child age goes here</p>
</div>
</div>
</div>
</div>
Allows Multiple Arguments: 🚫 NO
Examples
<div strapi-relation="children, people">
Marks the div element as a relation element with the relation defined in the field children for the collection called people.
<div strapi-relation="pets, animals">
Marks the div element as a relation element with the relation defined in the field pets for the collection called animals.
strapi-repeatable
The strapi-repeatable attribute specifies that the element is a repeatable element. Repeatable elements function identically to collection elements, except their data is not pulled from a strapi collection but rather the data in a collection entries field. This attribute is used to render either multi-media fields (multiple images, multiple videos, …) or repeatable components. Like collection elements, repeatable elements must contain templates. The field elements in those templates must use the name of you repeatable field (see below).
Below is the HTML to render the collection people, with a multiple media field of images called my_images.
Allows Multiple Arguments: 🚫 NO
Example
<div strapi-collection="people">
<div strapi-template="">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
<div strapi-repeatable="my_images">
<div strapi-template="">
<img strapi-field="my_images" />
</div>
</div>
</div>
</div>
The collection "people" will be rendered with a repeatable element for the field my_images.
CSS Modifiers
There are a number of attributes that can be used to modify the styling of your collections:
- strapi-background-image - Use an image from a Strapi entry as the background image of an element.
- strapi-class-add - Add a class to an element from a Strapi field.
- strapi-class-conditional - Add a class to an element conditionally, based on the value of a Strapi field.
- strapi-class-replace - Replace the class of an element with a class from a Strapi field.
strapi-class-add
The strapi-class-add attribute adds a class to an element with the name specified by the value in a Strapi field. These elements must exist as children of a template element. This allows the styling of elements to be changed through the Strapi CMS.
Below is the HTML to render a collection Person (plural people), with a strapi-class-add attribute to add a class to the p element, with the class decided by the value of the Strapi field color_class.
<div strapi-collection="people">
<div strapi-template="">
<p strapi-field="name" strapi-class-add="color_class">name</p>
</div>
</div>
Allows Multiple Arguments: ✅ YES
Examples
<div strapi-collection="people">
<div strapi-template="">
<p strapi-field="name" strapi-class-add="color_class">name</p>
</div>
</div>
Adds a class to the p element, with the class name given by the value in Strapi field color_class.
<div strapi-collection="people">
<div strapi-template="">
<p strapi-field="name" strapi-class-add="color_class | text_decoration_class">name</p>
</div>
</div>
Adds two classes to the p element, with the class names given by the values in Strapi fields color_class and text_decoration_class.
strapi-class-replace
The strapi-class-replace attribute replaces an existing class on an element with a class with name specified by the value in a Strapi field. This works similarly to strapi-class-add but can be used to replace an existing placeholder class. The Strapify Conditional Expression Arguments section details the conditional expression syntax.
Below is the HTML to render a collection Person (plural people), with a strapi-class-replace attribute to add a class to the p element and remove the existing class black, with the replacement class decided by the value of the Strapi field color_class.
<div strapi-collection="people">
<div strapi-template="">
<p
class="black"strapi-field
strapi-field="name"
strapi-class-replace="color_class, black"
>
name
</p>
</div>
</div>
Allows Multiple Arguments: ✅ YES
Examples
<div strapi-collection="people">
<div strapi-template="">
<p
class="black"
strapi-field="name"
strapi-class-replace="color_class, black"
>
name
</p>
</div>
</div>
Replaces the class black on the p element with a class which has its name stored in the Strapi field color_class.
<div strapi-collection="people">
<div strapi-template="">
<p
class="black bold"
strapi-field="name"
strapi-class-replace="color_class, black | text_decoration_class, bold"
>
name
</p>
</div>
</div>
Replaces the classes bold and black on the p element with classes which have their name stored in the Strapi fields text_decoration_class and color_class.
strapi-class-conditional
This attribute will add a class to an element if the expression is true. See the Strapify Conditional Expression Arguments for more information on the syntax of the expression.
This attribute can be used as an alternative to strapi-template-conditional to conditionally style an element element based on the values of Strapi data.
Allows Multiple Arguments: ✅ YES
Example
<div strapi-collection="articles">
<div strapi-template="">
<div
class="tag"
strapi-class-conditional="type == 'nature', green | type == 'sports', red"
>
<p strapi-field="type">Tag name here.</p>
</div>
<p strapi-field="title">title goes here</p>
<p strapi-field="author">author goes here</p>
</div>
</div>
Adds the class green to the div element if the value of the Strapi field type is nature, and adds the class red to the div element if the value of the Strapi field type is sports.
strapi-background-image
The strapi-background-image attribute is used to set a background image on another element. The value of the attribute is the name of the Strapi field that contains the image. The image must be a single image, not multiple images.
The CSS background-size is set to cover by default. To override this, you'll need to use !important in your CSS.
Below is an HTML example of the strapi-background-image attribute being used to set the background image of a div.
<div strapi-collection="countries">
<div strapi-template="" strapi-background-image="countryImage">
<h1 strapi-field="countryName"></h1>
</div>
</div>
Allowed Elements:
Any template element or child of a template element.
Allows Multiple Arguments: ✅ YES
Examples
<div strapi-template strapi-background-image="portraitPhoto">
<h3 strapi-field="name"></h3>
</div>
Sets the background image of the div to the value in the strapi field "portraitPhoto".
<div strapi-template>
<div strapi-background-image="portraitPhoto"></div>
<h3 strapi-field="name"></h3>
</div>
Sets the background image of the div to the value in the strapi field "portraitPhoto".
Auth System (Alpha)
Strapify provides a basic authentication system that can be used to authenticate users and register new users. It is intended for use on simple projects and it’s primary use is to show or hide Strapi collections depending on whether the user is logged in.
Please Note - The auth system stores the user's JWT in local storage. This is not secure and should not be used for sensitive data. Soon, the auth system will be updated to use secure cookies instead of local storage, but for now, please do not use the auth system for sensitive data.
The basic authentication system for Strapify consists of three parts:
- The strapi-auth attribute, which can be set to either "authenticate" or "register" to indicate the form's purpose.
- The strapi-auth-input attribute, which can be set to the Strapi data field. For login, the keyword "identifier" is reserved for the username. For registration, the attribute can be set to the field names such as "username", "email", "password" etc.
- The strapi-auth-submit attribute, which submits the form when clicked.
strapi-auth
Please Note - The auth system stores the user's JWT in local storage. This is not secure and should not be used for sensitive data. Soon, the auth system will be updated to use secure cookies instead of local storage, but for now, please do not use the auth system for sensitive data.
strapi-auth is the first attribute that should be added to a login or register form when configuring the Strapify authentication system.
The basic authentication system for Strapify consists of three parts:
- The
strapi-authattribute, which can be set to either "authenticate" or "register" to indicate the form's purpose. - The
strapi-auth-inputattribute, which can be set to the Strapi data field. For login, the keyword "identifier" is reserved for the username. For registration, the attribute can be set to the field names such as "username", "email", "password" etc. - The
strapi-auth-submitattribute, which submits the form when clicked.
The Strapify auth system is intended for use on simple projects and it’s primary use is to show or hide Strapi collections depending on whether the user is logged in.
Example of a login form:
<form strapi-auth="authenticate">
<label for="username">Username</label>
<input
type="text"
placeholder="Enter Username"
name="username"
strapi-auth-input="identifier"
required
/>
<label for="psw">Password</label>
<input
type="password"
placeholder="Enter Password"
name="psw"
strapi-auth-input="password"
required
/>
<button type="submit" strapi-auth-submit>Login</button>
</form>
Example of a registration form:
<form strapi-auth="register">
<label for="username">Username</label>
<input
type="text"
placeholder="Enter Username"
name="username"
strapi-auth-input="username"
required
/>
<label for="email">Email</label>
<input
type="text"
placeholder="Enter Email"
name="email"
strapi-auth-input="email"
required
/>
<label for="psw">Password</label>
<input
type="password"
placeholder="Enter Password"
name="psw"
strapi-auth-input="password"
required
/>
<button type="submit" strapi-auth-submit>Register</button>
</form>
Note: Make sure to use the correct field names corresponding to the fields in your Strapi user model.
Allowed Elements:
form
Allows Multiple Arguments: 🚫 NO
Examples:
<form strapi-auth="authenticate">
Marks the form element as a form that should authenticate users using the Strapify authentication system
<form strapi-auth="register">
Marks the form element as a form that should register users using the Strapify authentication system
strapi-auth-input
Please Note - The auth system stores the user's JWT in local storage. This is not secure and should not be used for sensitive data. Soon, the auth system will be updated to use secure cookies instead of local storage, but for now, please do not use the auth system for sensitive data.
strapi-auth-input is used inside a form where the strapi-auth attribute is being used. The strapi-auth-input attribute is used to specify the Strapi user field that the input element is associated with. The attribute value should match the field name in the Strapi user model. For example, in a registration form, the input element for the username field would have strapi-auth-input="username", and the input element for the email field would have strapi-auth-input="email".
When used in a login form, the strapi-auth-input attribute should be set to "identifier" to specify the username field.
Note that if you have one input field that you’d like applied to more than one Strapi user data field, you can use multiple arguments to accomplish this like so:
By far the most common use case for this is during registration, when one input field should submit it’s value as the new user’s username and email
<form strapi-auth="register">
<label for="email">Email</label>
<input
type="email"
placeholder="Enter Email"
name="email"
strapi-auth-input="username | email"
required
/>
<label for="psw">Password</label>
<input
type="password"
placeholder="Enter Password"
name="psw"
strapi-auth-input="password"
required
/>
<button type="submit" strapi-auth-submit>Login</button>
</form>
Allowed Elements:
input
Allows Multiple Arguments: ✅ YES
Examples
<input type="text" name="username" strapi-auth-input="identifier" />
Marks the username input as the identifier used for authentication (login).
<input type="text" name="username" strapi-auth-input="username">
Another username input, however this would be used for registration to set the new user’s username
<input type="text" name="username" strapi-auth-input="username | email">
Another username input, however this would be used for registration to set the new user’s username and email to the value entered in the username input.
strapi-auth-submit
Please Note - The auth system stores the user's JWT in local storage. This is not secure and should not be used for sensitive data. Soon, the auth system will be updated to use secure cookies instead of local storage, but for now, please do not use the auth system for sensitive data.
The strapi-auth-submitattribute should be used in strapi-auth forms to indicate the submit button. When clicked, it triggers the authentication process (either registration or login). The attribute is typically added to a <button> element of type "submit".
If strapi-auth is set to register, the form will attempt to create a new user from the credentials provided in the form inputs using strapi-auth-input.
If strapi-auth is set to authenticate, it will attempt to authenticate the user based on the credentials provided in the login form, and the user’s JWT token will be stored in localStorage.
Allowed Elements:
button
Allows Multiple Arguments: 🚫 NO
Examples:
See code example in strapi-auth
strapi-logout
Please Note - The auth system stores the user's JWT in local storage. This is not secure and should not be used for sensitive data. Soon, the auth system will be updated to use secure cookies instead of local storage, but for now, please do not use the auth system for sensitive data.
When set on a <button> element, the strapi-logout attribute will log out the user when the button is clicked. It can be used together with strapi-logout-redirect to destroy the token and redirect the user to another page.
Example
<button strapi-logout>Logout</button>
Log out the user when the button is clicked.
<button strapi-logout strapi-logout-redirect="/home">Logout</button>
Log out the user and redirect them to the /home page.
strapi-logout-redirect
Please Note - The auth system stores the user's JWT in local storage. This is not secure and should not be used for sensitive data. Soon, the auth system will be updated to use secure cookies instead of local storage, but for now, please do not use the auth system for sensitive data.
The strapi-logout-redirect attribute can be used on a strapi-logout element to redirect a user to a different URL when the element is clicked. This is useful for logging out a user and redirecting them to a different page.
Example
<button strapi-logout strapi-logout-redirect="/home">Logout</button>
Log out the user and redirect them to the /home page.
strapi-error-redirect
Please Note - The auth system stores the user's JWT in local storage. This is not secure and should not be used for sensitive data. Soon, the auth system will be updated to use secure cookies instead of local storage, but for now, please do not use the auth system for sensitive data.
The strapi-error-redirect attribute redirects a user to a different URL when a strapi-ezforms-form or strapi-auth form fails to submit. It should be added on the <form> component itself.
Example
<form strapi-ezforms-form strapi-error-redirect="/error">
Redirects the user to the error page when the form submission is unsuccessful
strapi-success-redirect
Please Note - The auth system stores the user's JWT in local storage. This is not secure and should not be used for sensitive data. Soon, the auth system will be updated to use secure cookies instead of local storage, but for now, please do not use the auth system for sensitive data.
The strapi-success-redirect attribute redirects a user to a different URL when a strapi-ezforms-form or strapi-auth form is successfully submitted. It should be added on the <form> component itself.
Example
<form strapi-ezforms-form strapi-success-redirect="/success">
Redirects the user to the success page when the form submission is successful
EZForms
Strapify integrates with the Strapi EZForms plugin to allow you to easily connect your HTML forms to your Strapi backend. Simply add the strapi-ezforms-form and strapi-ezforms-submit to the submit button of that form and you're ready to go!
Note that the EZForms Plugin needs to be installed and configured on your Strapi backend for this to work. EZForms does not include file uploads, so if you need to upload files, you may want to use a different method.
strapi-ezforms-form
The strapi-ezforms-form attributes is used on form elements to identify the form as one which will submit form data to the EZForms plugin endpoints in Strapi.
The strapi EZForms plugin will have to be installed and configured. Once installed, the plugin will create two collections: "Form Sumbissions" and "Notification Recipients". The "Form Submissions" collection will be used to store form submissions, and the "Notification Recipients" collection will be used to store email addresses that will receive notifications when a form is submitted. An email provider may also be configured if you’d like to receive email notifications on form submissions.
When submitted, it emits two custom events: strapiEZFormsSubmitted and strapiEZFormsError. These events can be used to trigger UI changes or other custom logic on form submission.
There are two other simple ways to trigger UI changes on form submission.
- You can set
strapi-state-elementon an element to show/hide elements depending on the state of the form submission. The two key values would bestrapi-state-element="success", to be set on the element you’d like to show when the user successfully submits the form, andstrapi-state-element="error", to be set on the element you’d like to show when the form submission fails. - You can use
strapi-success-redirectorstrapi-error-redirectto redirect to a different URL when a form submission succeeds or fails.
Below is the HTML to configure a form with strapi-ezforms-form
<form strapi-ezforms-form>
<label for="username">Email</label>
<input type="email" placeholder="Enter Email" name="email" required />
<label for="message">Your Message</label>
<input type="password" placeholder="Enter Password" name="psw" required />
<button type="submit" strapi-ezforms-submit>Submit</button>
</form>
Strapify automatically parses all of the form’s input fields. The form’s input fields will be sent to the Strapi EZForms plugin endpoint as a JSON object. The JSON object will be stored in the "Form Submissions" collection in Strapi. The keys of the JSON object will be the names of the input fields, and the values will be the values of the input fields.
Allowed Elements:
form
Allows Multiple Arguments: 🚫 NO
Example
See code example above
strapi-ezforms-submit
The strapi-ezforms-submit attribute should be used in strapi-ezforms-form forms to indicate the submit button. When clicked, it triggers the form submission process. The attribute is typically added to a <button> element of type "submit".
Allowed Elements:
button
Allows Multiple Arguments: 🚫 NO
Example
See code example in strapi-ezforms-form
strapi-error-redirect
The strapi-error-redirect attribute redirects a user to a different URL when a strapi-ezforms-form or strapi-auth form fails to submit. It should be added on the <form> component itself.
Example
<form strapi-ezforms-form strapi-error-redirect="/error">
Redirects the user to the error page when the form submission is unsuccessful
strapi-success-redirect
The strapi-success-redirect attribute redirects a user to a different URL when a strapi-ezforms-form or strapi-auth form is successfully submitted. It should be added on the <form> component itself.
Example
<form strapi-ezforms-form strapi-success-redirect="/success">
Redirects the user to the success page when the form submission is successful
State Elements (Error, Loading, Success)
Strapify provides a set of attributes that can be used to display the state of a Strapi collection or single type. These attributes can be used to display a loading spinner, an error message, or a success message.
These attributes are:
strapi-state-element
The strapi-state-element attribute specifies an element to be hidden or shown based on the state of the parent Strapify element. Elements with this attribute must be a descendant of an element with a strapi-collection, strapi-relation, strapi-repeatable, strapi-single-type-relation, strapi-single-type-repeatable, strapi-auth, strapi-form or strapi-ezforms-form attribute.
The possible values are loading, error and success. This is useful to show an element that indicates the collection is loading, or to display error/success messages to the user. It may also be used to display success/error messages on form and auth register/login attempts.
Below is the HTML to render a collection Person (plural people), with three state elements to display a message indicating an error, success or a loading state.
<div strapi-collection="people">
<div strapi-template="">
<p strapi-field="name">name</p>
<p strapi-field="age">age</p>
</div>
<p strapi-state-element="loading">LOADING...</p>
<p></p>
<p strapi-state-element="success">SUCCESS</p>
<p></p>
<p strapi-state-element="error">ERROR</p>
<p></p>
</div>
Below is the HTML to use state elements with a strapi-auth element.
<form strapi-auth="authenticate">
<label for="username">Username</label>
<input
type="text"
placeholder="Enter Username"
name="username"
strapi-auth-input="identifier"
required
/>
<label for="psw">Password</label>
<input
type="password"
placeholder="Enter Password"
name="psw"
strapi-auth-input="password"
required
/>
<button type="submit" strapi-auth-submit>Login</button>
<p strapi-state-element="loading">LOADING...</p>
<p></p>
<p strapi-state-element="success">SUCCESS</p>
<p></p>
<p strapi-state-element="error">ERROR</p>
<p></p>
</form>
Allows Multiple Arguments: 🚫 NO
Examples
<p strapi-state-element="loading">LOADING...</p>
The p element is displayed only when the parent collection element is loading the Strapi data.
<p strapi-state-element="success">SUCCESS</p>
The p element is displayed only when the parent collection element has loaded the data and finished rendering.
<p strapi-state-element="error">ERROR</p>
The p element is displayed only when the parent collection element has failed to retrieve the Strapi data.
strapi-hide-on-fail
The strapi-hide-on-fail attribute will cause a collection element, relation element or repeatable element to be hidden in the case that an error occurred when fetching data. This attribute is useful in scenarios for which failure is expected, such as when the collection is only available to authenticated users but the current user has not yet authenticated. It may also be used to hide data if there is an unexpected error, but state elements should be preferred in such cases.
Strapify currently accomplishes this by adding a class with CSS attribute display: none; on the element. It will not work if you have specified the CSS display attribute inline or with !important.
Below is the HTML to hide a collection in the case that there is an error retrieving the collection data.
<div strapi-collection="people" strapi-hide-on-fail="">
<div strapi-template="">
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
</div>
</div>
Allows Multiple Arguments: 🚫 NO
Examples:
<div strapi-collection="people" strapi-hide-on-fail>
<div strapi-template>
The template to be hidden if there is an error
<p strapi-field="name">name goes here</p>
<p strapi-field="age">age goes here</p>
</div>
Strapify will attempt to render the collection People. If an error occurs, the element will become hidden.
Single Type Elements
Single Type Elements are used to display data from a single type. They are used in the same way as Collection Elements, but they are used to display data from a Strapi single type instead of a collection type.
In most cases, Single types do not need to exist as children of a template element, unlike Collection Elements.
strapi-single-type
The strapi-single-type attribute works much the same as strapi-field, but does not need to exist as a child of a template element; it can exist anywhere. Instead, this attribute will cause the value of a Strapi single type field to be rendered in the element.
| Strapi Field Type | HTML Elements | Comments |
|---|---|---|
| Text | p h span div | The div is typically invalid but can be used as a special case to embed a video. For it to work, your text field must contain a link and the div must contain an iframe child element. |
| p h span | Field data will be inserted as text content. | |
| Rich Text | div | HTML elements will be created in the div to render the rich text. |
| Number | p h span | Field data will be inserted as text content. |
| Enumeration | p h span | Field data will be inserted as text content. |
| Date | p h span | Field data will be inserted as text content. |
| Media (Image) | img | The image source will be set to point to the Strapi url for the image. |
| Media (Video) | div | A video element will be inserted into the div. |
| Boolean | p h span | Field data will be inserted as text content. |
Below is the HTML to render a few fields from the single type collection info.
<div>
<h1 strapi-single-type="info.company_name">Company Name</h1>
<img strapi-single-type="info.company_image" />
<div strapi-single-type="info.bio">
<p>placeholder for bio<p>
</div>
</div
Allows Multiple Arguments: 🚫 NO
Examples:
<p strapi-single-type="info.name"></p>
Render the value in the Strapi single type field name for the single type collection info.
<p strapi-single-type="home_page.title"></p>
Render the value in the Strapi single type field title for the single type collection home_page.
<p strapi-single-type="home_page.article.title"></p>
Render the value in title, which is an element of a component called article which belongs to the home_page single type collection.
strapi-single-type-into
The strapi-single-type-into attribute is used to pass data from a Strapi single type collection field directly into an HTML attribute.
Below is the HTML to set the alt text of the img element to the value held in the Strapi single type field alt_text.
<img
strapi-single-type-field="info.company_image"
strapi-into="info.company_image_alt_text -> alt"
/>
Allowed Elements:
Any.
Allows Multiple Arguments: ✅ YES
Examples:
<img
strapi-single-type-field="info.company_image"
strapi-into="info.company_image_alt_text -> alt"
/>
Sets the alt attribute of the img element to the value in the strapi single type field alt_text of the collection info.
<img
strapi-single-type-field="home_page"
strapi-into="home_page.element_id -> id | home_page.alt_text -> alt"
/>
Sets the id of the img element to the value in the Strapi single type field element_id and sets the alt attribute of the img element to the value in the Strapi single type field alt_text of the collection home_page.
strapi-single-type-background-image
The strapi-single-type-background-image works the same as the strapi-background-image attribute, but it is used on a single type element instead of a collection element.
Example
<div strapi-single-type-background-image="homepage.background">
<h1 strapi-single-type="homepage.title"></h1>
<p strapi-single-type="homepage.text">Some text</p>
</div>
This example sets the background image of the div to the value in the single type "homepage" with the field "background".
strapi-single-type-class-add
The strapi-single-type-class-add attribute works much the same as strapi-class-add attribute, but can be used on a single type element instead of a collection element.
This attribute will cause the value of a Strapi single type field to be added to an element’s class list.
Below is the HTML to render a the Strapi single type field company_name of the single type collection info. The strapi-single-type-class-add attribute causes the value of the field company_name_color_class from the info collection to be added to the h1 element’s class list.
Allows Multiple Arguments: ✅ YES
Example
<h1
strapi-single-type-field="info.company_name"
strapi-class-add="info.company_name_color_class"
>
company name
</h1>
strapi-single-type-class-replace
The strapi-single-type-class-replace attribute works much the same as strapi-class-replace attribute, but does not need to exist as a child of a template element; it can exist anywhere. Instead, this attribute will cause the value of a Strapi single type field to be added to an element’s class list, replacing an the specified existing class.
<h1
strapi-single-type-field="info.company_name"
strapi-class-replace="info.company_name_color_class, black"
>
company name
</h1>
strapi-single-type-class-conditional
The strapi-single-type-class-conditional attribute works much the same as the strapi-class-conditional attribute, but can be used on a single type element instead of a collection element.
This attribute will add a class to an element if the expression is true. See the Strapify Conditional Expression Arguments for more information on the syntax of the expression.
Example
<div strapi-collection="articles">
<div strapi-template="">
<div
class="tag"
strapi-class-conditional="type == 'nature', green | type == 'sports', red"
>
<p strapi-field="type">Tag name here.</p>
</div>
<p strapi-field="title">title goes here</p>
<p strapi-field="author">author goes here</p>
</div>
</div>
Adds the class green to the div element if the value of the Strapi field type is nature, and adds the class red to the div element if the value of the Strapi field type is sports.
Unlike the strapi-class-conditional attribute, does not need to exist as a child of a template element; it can exist anywhere.
strapi-single-type-repeatable
The strapi-single-type-repeatable attribute works much the same as the strapi-repeatable attribute, but can be used for repeatable single types. It also does not need to exist as a child of a template element, unlike the strapi-repeatable attribute.
strapi-single-type-relation
The strapi-single-type-relation attribute works much the same as the strapi-relation attribute, but is used on single types instead of collection types. It also does not need to exist as a child of a template element, unlike the strapi-relation attribute.
Below is the HTML to render the single type field employees which belongs to the Company single type. The employees field is a relation with the collection Person (people).
<div strapi-single-type-relation="Company.employees, people">
<div strapi-template="">
<p strapi-field="name">employee name goes here</p>
<p strapi-field="age">employee age goes here</p>
</div>
</div>
Allows Multiple Arguments: 🚫 NO
Examples:
See above
Using Scripts with Strapify
While Strapify generally works fine with other scripts, it is sometimes important to consider the order in which your scripts are loaded if they are dependent on each other.
Strapify will run after the DOMContentLoaded event has been emitted. This will ensure that any non async scripts will be executed before Strapify runs. If you would like a script to run before Strapify, but after the page has loaded, you should use a deferred script. If you would like a script to run after Strapify runs, you should wait for the strapifyInitialized event to be emitted on the document.
Attribute Mutations
Some Strapify elements will automatically respond to changes made to their HTML attributes. When these mutations occur the collection will rerender using the new the attribute values. This allows custom scripts to change the filter, sort and page of collection elements, for example.
Elements that support attribute mutations:
- collection elements
- field elements
- relation elements
- repeatable elements
- single type field elements
Below is an example of how to mutate a the strapi-filter value on a Strapify collection.
// select a collection element so we can change its strapi-filter-control value
const collectionElement = document.querySelector("#people-collection");
// Set the new attribute value and Strapify will rerender the collection accordingly
collectionElement.setAttribute("strapi-filter", "[name][$eq]=Austin");
Events
Strapify emits custom events that can be used with JavaScript to build on top of the base functionality.
The events that are emitted are:
- strapiCollectionChange
- strapiAuthRegistered
- strapiAuthRegisterError
- strapiAuthLoggedIn
- strapiAuthLogInError
- strapiUserAuthenticated
- strapiUserAuthenticationError
strapifyInitialized
The strapifyInitialized event is emitted when strapify finishes rendering for the first time. All Strapi data will have been rendered to the DOM before this event occurs.
Below is an example of how to use the strapifyInitialized event.
//emitted when strapify finishes rendering for the first time
//all Strapi data will have been rendered to the DOM before this event occurs
document.addEventListener("strapifyInitialized", (event) => {
//you have access the authentication state and the user data if authenticated
const userAuthenticated = event.detail.userAuthenticated;
const userData = event.detail.user;
//custom code that interacts with strapify...
//or any custom code that requires that strapify has already rendered...
//or any custom code that requires access to authenticated user information...
});
strapiCollectionChange
This event is emitted when a collection, relation or repeatable element is rerendered or rendered for the first time.
Below is an example of how to use the strapiCollectionChange event. This event is use on collection, relation and repeatable elements.
//query select a collection element to which you would like to listen for changes
const peopleCollectionElement = document.querySelector("#people-collection");
//event emitted when the collection is rerendered or rendered for the first time
peopleCollectionElement.addEventListener(
"strapifyCollectionChange",
(event) => {
//you have access to the collection element that changed and the collection data that was fetched.
const collectionElement = event.target;
const strapiCollectionData = event.detail.collectionData;
//custom code...
}
);
strapiAuthRegistered
The strapiAuthRegistered event is emitted when a user has successfully registered.
Below is an example of how to use the strapiAuthRegistered event.
//query select an auth element to which you would like to listen for a successful registration
const formElement = document.querySelector("#register-form");
//event emitted when the user has submitted the form and the registration succeeded
formElement.addEventListener("strapiAuthRegistered", (event) => {
//you have access the authenticated user data
const userData = event.detail.user;
//custom code...
});
strapiAuthRegisterError
The strapiAuthRegisterError event is emitted when a user has submitted the registration form and the registration has failed.
Below is an example of how to use the strapiAuthRegisterError event.
//query select an auth element to which you would like to listen for a failed registration
const formElement = document.querySelector("#register-form");
//event emitted when the user has submitted the form and the registration failed
formElement.addEventListener("strapiAuthRegisterError", (event) => {
//you have access to the error message and the full javascript error
const error = event.detail.error;
const errorMessage = event.detail.errorMessage;
//custom code...
});
strapiAuthLoggedIn
This event is emitted when the user has submitted the login form and the log in succeeded.
Below is an example of how to use the strapiAuthLoggedIn event.
//query select an auth element to which you would like to listen for a successful log in.
const formElement = document.querySelector("#login-form");
//event emitted when the user has submitted the login form and the log in succeeded
formElement.addEventListener("strapiAuthLoggedIn", (event) => {
//you have access the authenticated user data
const userData = event.detail.user;
//custom code...
});
strapiAuthLoginError
This event is emitted when the user has submitted the login form and the log in failed.
Below is an example of how to use the strapiAuthLogInError event.
//query select an auth element to which you would like to listen for a failed log in.
const formElement = document.querySelector("#login-form");
//event emitted when the user has submitted the login form and the log in failed
formElement.addEventListener("strapiAuthLoggedIn", (event) => {
//you have access the authenticated user data
const userData = event.detail.user;
//custom code...
});
strapiUserAuthenticated
This event is emitted when Strapify runs and validates existing user data from local storage.
Below is an example of how to use the strapiUserAuthenticated event.
//event emitted when Strapify runs and validates existing user data from local storage
document.addEventListener("strapiUserAuthenticated", (event) => {
//you have access the authenticated user data
const userData = event.detail.user;
//custom code...
});
strapiUserAuthenticationError
This event is emitted when Strapify runs and failed to validate existing user data.
Below is an example of how to use the strapiUserAuthenticationError event. When user data is found but could not be validated this event will fire. Currently, the invalid user data is just deleted and the page is reloaded immediately, so this event will never be used at the moment. An option to prevent an automatic page reload may be added in the future.
//event emitted when Strapify runs and failed to validate existing user data
document.addEventListener("strapiUserAuthenticationError", (event) => {
//custom code...
});
Syntax Notes
There are a few syntax rules that are important to understand when using Strapify. Those rules are described in detail below.
- Arguments
- Multiple Arguments
- Components in Arguments
- Variable Templating in Arguments
- Query String Variables in Arguments
- Strapi Sort & Filter Syntax
- Strapify Conditional Expression Arguments
- Special Characters
Arguments
An argument is the value you give to a strapi attribute when it is created. For example, in the following line,
strapi-collection="cards"
cards is said to be the argument.
In the next line,
strapi-into="alt_text -> alt"
alt_text → alt is said to be the argument*.*
There are a few important rules (conforming to the Strapi rest API) that should be remembered when referring to Strapi collection names and field names.:
- Collections are always described by their plural name: (cards is valid while card is not)
- If a collection name contains underscores, those underscores should be replaced with dashes when referring to the collection: (some-collection is valid while some_collection is not)
- Collection names are not case sensitive: (cards is equivalent to Cards)
- Field names are case sensitive: (name is NOT equivalent to Name)
- Field names should not have underscores replaced with dashes: (field_name is valid while field-name is not)
Multiple Arguments
Some attributes such as strapi-class-add, can accept multiple arguments as a value. These arguments are given as | (vertical bar/pipe) separated values. When multiple arguments are given in an attribute value, Strapify will function as if two attributes of the same name but different values were given. For example,
`strapi-class-add="layout-class | color-class"`
will cause both the class names given in the Strapi fields layout-class and color-class to be added to class list of the element containing the attribute. It is not valid to define two attributes of the same name on an element, so the | syntax must be used.
Components in Arguments
To reference a Strapi field contained in a component, you write the field name of the component and then the name of the field in the component, separated by a . (period). For example,
strapi-field="name.first"
would refer to the field with field name first within the component with field name name.
This also works with nested components like so
strapi-field="employee.name.first"
which refers to a field called first which exists within a component name which exists within a component employee.
Variable Templating in Arguments
Some attributes (see below) accept a template as an argument; a string which may contain references to Strapi fields. Strapi fields are referenced by giving the field name wrapped in double curly braces {{}}.
For example,
background: {{background_color}}; would be transformed into background: red;.
An attribute using the above template would look like this,
strapi-css-rule="background: {{background_color}};".
This attribute would create an inline CSS rule for the element, with a substitution of the value held in the Strapi field background_color in place of {{background_color}}.
Attributes that accept variable template arguments:
strapi-into, strapi-css-rule, strapi-single-type-into, strapi-single-type-css-rule
Query String Variables in Arguments
Query string arguments are arguments that contain a placeholder for a value contained in the current page’s query string, notated by a qs. prefix, example: qs.varName. When strapify finds an occurrence of a query string argument, it will be replaced entirely by the value of the query string parameter with the specified name. For example qs.varName would be replaced by varValue if the query string for the page was ?varName=varValue. A few more examples are shown in the table below. Query string variables may be used in any Strapify attribute value.
| Website Query String | Given Attribute Value | Strapify Uses |
|---|---|---|
| ?message=hello | qs.message | hello |
| ?nameComponentField=first | name.qs.nameComponentField | name.first |
| ?title=movie review | [title][$eq]=qs.title | [title][$eq]=movie review |
There may be situations where you wish to render a single entry in a Strapi collection on a dedicated page. For example, if you had a collection Blogs, you may wish to have a separate page for each Blog belonging to Blogs. Strapify allows this situations through query string arguments, which you would write in the URL when you link to the page for the blog. Consider the following Strapi collection.
collection name: Blog
- field name: title
- field name: rich_text
Now let’s say you want to have a page for a blog in the collection with title “fun day at the beach.” and another page for a blog with title “bad day at home.”. To do this create a page called www.yourwebsite.com/blog and on that page, create a collection element as you would normally. Now to link to that URL in a way that will allow you display only the “fun day at the beach blog”, you would use the URL www.yourwebsite.com/blog?title=fun day at the beach. On your blog page, the query string parameter will be available in your strapi arguments, which you can use to filter out a single blog to display. You would use the following attributes on the collection element your created:
strapi-collection="blogs" , strapi-filter="[title][$eq]=qs.title"
If you wanted to instead link to the blog with title “bad day at home”, you would use the URL www.yourwebsite.com/blog?title=bad day at home.
Strapi Sort & Filter Syntax
Some attributes, such as strapi-filter and strapi-sort accept arguments arguments conforming to Strapi query string API parameters. The syntax for these attributes is identical to the Strapi query string API, except the identifier for the query string parameter is omitted. For example, consider the query string parameter sort=age , which might appear in a Strapi request like localhost:1337/api/people?sort=age. To achieve this in strapify you would give the attribute strapi-sort the argument age. Similarly for filters, the query string parameter filters[name][$eq]=Paul Dirac would become [name][$eq]=Paul Dirac when used with a the strapi-filter attribute.
When making a Strapi request, it is possible to include multiple of the same query string parameter. For example, you might have a request like localhost:1337/api/people?sort=name&sort=age:desc which would would sort the collection people by name and then by age descending. This is accomplished in Strapify by providing multiple arguments to the strapi-sort attribute with the value name | age:desc . Filters work similarly, if you had the request url localhost:1337/api/people?filters[$and][0][name][$eq]=Paul Dirac&filters[$and][1][age][$eq]=82, you would give strapi-filter the value [$and][0][name][$eq]=Paul Dirac | [$and][1][age][$eq]=82 .
There is one important difference between the Strapi query string API syntax and the Strapify syntax: equality operators must always be prefixed with [$eq] in Strapify arguments. For example, [name][$eq]=Paul Dirac is valid while [name]=Paul Dirac is not. This is due to the fact that while Strapi will allow the [$eq] part to be omitted when all other occurrences of the equality operator also omit it, Strapify uses the full [$eq]= syntax internally. If Strapify receives arguments using = instead of [$eq]= , invalid requests will be made and your Strapi data will not be fetched.
Strapify Conditional Expression Arguments
There are Strapify attributes that require a conditional expression to be given as an argument, namely strapi-template-conditional and strapi-class-conditional . The conditional expressions are written using a syntax specific to Strapify. The syntax is similar to popular programming languages such as C, Java, Javascript and Python, though much more primitive. A Strapify conditional expression may contain operands, operators and groups. Operands are values which are to be compared to one another, using a comparison operator. Operators, such as == and &&, define how two operands or sub-expression groups are to be compared or logically composed. Groups are sub-expressions contained within round bracket parentheses, used to impose an order of logical operations. Strapify will take any Strapi data and query string variable data to make the specified comparisons to produce a boolean value representing whether or not the condition is met.
Below are the allowed operands types with a few examples:
- integer literals:
132 - float literals:
1.054.43 - string literals:
'hello world''32''true'' ' - boolean literals:
truefalse - null literals:
nullundefined - Strapi field variables:
agename.firstis_employed - Strapify query string variables:
qs.titleqs.queryStringVarName
Below are the allowed operators with some examples:
- equality:
age == 24name == 'Paul Dirac'is_employed == falsefavorite_food == nullname.first == name.lasttitle == qs.title - not equal to:
age != 24name != 'Paul Dirac'is_employed != falsescore != 3.5favorite_food != null - less than:
age < 33score < 8 - less than or equal to:
age <= 33score <= 8 - greater than:
age > 33score > 8 - greater than or equal to:
age >= 33score >= 8 - and:
name == 'Paul Dirac' && age == 82is_employed == true && favorite_food == 'Pizza' - or:
name == 'Paul Dirac' || age == 82is_employed == true || favorite_food == 'Pizza'
Expressions must always be split into groups (with parentheses) when using more than one logical operator. The following are valid examples:
name == 'Paul Dirac' && age == 82(name == 'Paul Dirac' && age == 82) || is_employed == false(name == 'Paul Dirac' && age == 82) || (is_employed == false && score == 3.0)
Special Characters
- Note that some special characters including ampersands (&) should be encoded manually in your attribute values. For example if you’re trying to filter by a Category field equal to “Rice & Beans”, the value would be
strapi-filter=[Category][$eq]=Rice %26 Beansrather thanstrapi-filter=[Category][$eq]=Rice & Beans
Supported Strapi Field Types
Supported Strapi Field Types:
✅ Supported ⚠️ Work In Progress - do not use 🚫 Not Supported - do not use
To request support for a strapi extension, plugin or feature, email agoodman@civiconnect.ca.
Supported Plugins
Reserved Keywords
You must not use the following words as the names of Strapi collections, fields, components, etc…
- qs
- ls
- me
- true
- false
- undefined
- null
Changelog
1.0.0
initial release
1.0.1
Strapify now hides strapi-single-type and strapi-template elements until their content has been loaded (only when script is not deferred)
1.0.2
Enable pagination with strapi-repeatable
1.0.3
Added strapi-background-image, allow strapi-field and strapi-template to be defined on the same element
1.0.4
Fix breaking bug caused by lookbehind regex on mobile, added console message for basic errors
1.0.5
Add strapi-template-id attribute containing the ID to template elms (only on standard templates, not repeatables or relations).
1.0.6
Use babel to improve cross-browser compatibility, implement strapi-single-type-background-image
Contributing
Contributions are always welcome, no matter how large or small.
The GitHub repository for Strapify is located here
If you would like to contribute to Strapify, please follow these steps:
- Fork the repository
- Create a new branch
- Make your changes
- Create a pull request
Thank you for your interest in contributing to Strapify!
License
The MIT License (MIT)
Copyright © 2023 Strapify Contributors (Austin Goodman, Ray Keating, Civiconnect)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.