# Overview
If you can't find what you are looking for in our documentation you can submit a support ticket at [boldminded.com/support](https://boldminded.com/support).
{% hint style="warning" %}
All add-ons currently require PHP 8.2 or greater.
**On July 4th 2024 PHP 8.2 became the new minimum requirement for all add-ons**. Expect any add-on released after that date to require 8.2 or greater. Some releases may not immediately take advantage of 8.x specific features in PHP, which means you *might* be able to continue using new releases in PHP 7.4, however, if you experience an error the first thing you should do is update to PHP 8.2 *then* create a support ticket if the error persists.
{% endhint %}
{% content-ref url="/pages/puLaEUuQXlYKiuOVid2c" %}
[Advanced Categories](/advanced-categories/docs)
{% endcontent-ref %}
{% content-ref url="/pages/8Islf32r3CN9A2F5Ni13" %}
[Ansel](/ansel/docs)
{% endcontent-ref %}
{% content-ref url="/pages/-LyL6z1cJM9KfjYeUBuV" %}
[Bloqs](/bloqs/docs)
{% endcontent-ref %}
{% content-ref url="/pages/HU3UkPny8fqRzeqLIMCb" %}
[Carson](/carson/docs)
{% endcontent-ref %}
{% content-ref url="/pages/-LyovuWaL\_p06BX3tf-A" %}
[Custom System Messages](/custom-system-messages/docs)
{% endcontent-ref %}
{% content-ref url="/pages/VLcBbSOCLHXLUHehfD6p" %}
[DataGrab](/datagrab/docs)
{% endcontent-ref %}
{% content-ref url="/pages/0R5yDj5TqhQP04WZ7WhY" %}
[Dexter](/dexter/docs)
{% endcontent-ref %}
{% content-ref url="/pages/05D2qBsmEXGrzd1lAnqu" %}
[Fluidity](/fluidity/docs)
{% endcontent-ref %}
{% content-ref url="/pages/-MUPHzpS9okMnUbOkBKt" %}
[Logit](/logit/docs)
{% endcontent-ref %}
{% content-ref url="/pages/-Ly1iZcylBgjZTVd5ijR" %}
[Publisher](/publisher/docs)
{% endcontent-ref %}
{% content-ref url="/pages/-LyovpC5XYnt7LfTloTw" %}
[Reading Time PRo](/reading-time-pro/docs)
{% endcontent-ref %}
{% content-ref url="/pages/-LyoviZGQdLEzAoZ5qDW" %}
[Reel](/reel/docs)
{% endcontent-ref %}
{% content-ref url="/pages/-LyovnPhMV9ko8hSpIXa" %}
[Simple Grids & Tables](/simple-grids-and-tables/docs)
{% endcontent-ref %}
{% content-ref url="/pages/CYSkfanBGptSrsONpeSq" %}
[Sitemap](/sitemap/docs)
{% endcontent-ref %}
{% content-ref url="/pages/0zJ6HIL5FOwUPXJ2TmbV" %}
[Snaptcha](/snaptcha/docs)
{% endcontent-ref %}
{% content-ref url="/pages/-Ly1iUSY-9XhRmMXotEx" %}
[Speedy](/speedy/docs)
{% endcontent-ref %}
# Docs
{% hint style="danger" %}
Advanced Categories has been deprecated and is no longer for sale or supported. ExpressionEngine 7.4 introduces many of Advanced Categories features as natively to ExpressionEngine.
{% endhint %}
# Installation
{% hint style="danger" %}
Advanced Categories has been deprecated and is no longer for sale or supported. ExpressionEngine 7.4 introduces many of Advanced Categories features as natively to ExpressionEngine.
{% endhint %}
To install Advanced Categories, unzip the zip file and place the `advanced_catgories` folder into your `/system/user/addons` folder. Then login to the Control Panel and go to ***Developer >*** ***Add-ons*** from the main menu and click ***Install*** Advanced Categories.
# Requirements
{% hint style="danger" %}
Advanced Categories has been deprecated and is no longer for sale or supported. ExpressionEngine 7.4 introduces many of Advanced Categories features as natively to ExpressionEngine.
{% endhint %}
## Required
* ExpressionEngine 6.4.0 or greater
* PHP 7.4 or greater
### Recommended
[Good use of ExpressionEngine's Publish Layouts](/advanced-categories/docs/setup-and-configuration)
# Setup & Configuration
{% hint style="danger" %}
Advanced Categories has been deprecated and is no longer for sale or supported. ExpressionEngine 7.4 introduces many of Advanced Categories features as natively to ExpressionEngine.
{% endhint %}
Advanced Categories is a custom fieldtype that acts as a facade to manage assignment of categories to entries in ExpressionEngine. Before an entry is saved, the values from the Advanced Categories field are assigned to the ChannelEntry object the same way a normal category field assigns its values. As far as ExpressionEngine is concerned, an Advanced Category field is just a category group assigned to an entry.
{% hint style="warning" %}
**There are 2 important things to note when using Advanced Categories**:
1. Category groups must still be assigned to a channel. You can not add an Advanced Categories field to a channel, assign categories to the field, and expect it to work. Advanced Categories will only display categories that are also natively assigned to the channel through the channel management settings.
2. When using Advanced Categories it is highly recommended to use Publish Layouts to change the display of the default category groups in the Categories tab. Hide category groups that are made irrelevant based on how your Advanced Categories field is configured.
{% endhint %}
On the left, in the image below, is a default view of an entry publish page when 3 category groups are assigned to the channel, and on the right are 2 Advanced Category fields assigned to the channel. They look very similar, and that is by design, however, they behave differently. The "Call Signs" field on the right has been configured to require at least 1 category selection, but no more than 3. It also happens to be listing the same categories from the Call Signs category group on the left. The rules, and each of the category options were selected to display in the "Call Signs" field settings page. If the default category group remains visible on the publish page users can still interact with it, but if *any* category in the default category group is assigned as an option in an Advanced Categories field, then the categories selected in the Advanced Categories field will superceed anything selected in the default category group.
If an Advanced Categories field lists category options from more than 1 category group, and only a single category is selected, such as the Primary Category field on the right, then all other category groups that have a category as an option in the Advanced Categories field will be deselected. For example, if the default category group "Fruits" was not removed from the Categories tab using a Publish Layout, and the user selected "Apple", but then selected "First Order" from the "Primary Category" field, "Apple" would be deselected and not saved to the entry. This would happen even if the "Primary Category" field allowed more than 1 category to be selected. If no categories from the "Fruits" group were selected in an Advanced Categories field, then no categories from that group are saved to the entry.
## Using Publish Layouts
Now that you know how Advanced Category fields work, you can take advantage of Publish Layouts. Below we see the Advanced Categories field called "Primary Category" along side the default "Call Signs" category group in the Categories tab. By taking advantage of Publish Layouts, you can use Advanced Categories to offer more control over entry category assignment. If an Advanced Categories field is meant to replace an existing category group (or multiple groups), then you may want to consider hiding those groups.
## Rules
One of the main reasons Advanced Categories exists is to be able to assign rules to entry category assignments. The default category group fields do not offer the ability to require a number of categories to be selected, nor can they prevent more than 1 category from the group from being selected. Sometimes you need to be able to have such control over category assignments.
In this example, the field has a rule to require at least 1, but no more than 3 categories to be selected. Once 3 selections have been made the other options are disabled preventing additional selections. You can also add custom instruction to the field, which is something you can not do with a category group.
If a field does not pass validation, you will be informed as such, just like you would any other custom field on the entry.
# Hidden Config Options
`$config['advanced_categories_nuclear'] = 'yes';`
Enabling this option will only save categories from Advanced Categories fields. This means if there is 1 Advanced Categories field, and 5 category groups assigned to an entry then any selected category in the native category field groups will be unselected unless it's selected in an Advanced Categories field on the entry.
# Multi-Site Manager
Advanced Categories works in an MSM install, however, there are some things to be aware of.
* ExpressionEngine lets you share custom fields across multiple sites.
* ExpressionEngine does not let you share category groups across sites.
For those reasons, and based on what Advanced Categories is intended to do, you can not share an Advanced Category field across multiple sites. You will need to make an Advanced Category field unique to each MSM site you are running.
# Template Tags
{% hint style="danger" %}
Advanced Categories has been deprecated and is no longer for sale or supported. ExpressionEngine 7.4 introduces many of Advanced Categories features as natively to ExpressionEngine.
{% endhint %}
Advanced Categories is a fieldtype, and as such it works just like any other fieldtype in ExpressionEngine. The following examples assume you created a custom field with the label of "My Category Field", and the field template short name is `{my_category_field}`
Every Advanced Categories field is a tag pair, and even though it is a field, the tag pair functions almost exactly the same as the `{categories}{/categories}` tag pair from the `{exp:channel:entries}` tag ([see ExpressionEngine docs](https://docs.expressionengine.com/latest/channels/entries.html#categories)).
```
{exp:channel:entries}
{title}
{my_category_field}
{category_id}
{category_name}
{category_image}
{category_description}
{category_group}
{my_custom_category_field_1}
{my_custom_category_field_2}
{path="path/to/category/page"}
{category_total_results} or {total_results}
{category_count} or {count}
{/my_category_field}
{/exp:channel:entries}
```
{% hint style="warning" %}
This tag pair does not have support for the `show` or `show_group` parameters
{% endhint %}
Since it is also a fieldtype you have access to several tag modifiers:
`{my_category_field:ids}`\
This will list all the IDs of the categories chosen in the field separated by pipe. For example: `1|2|3`. If only a single category is selected, then its output would be that category ID.
`{my_category_field:url_titles}`\
This will list all the IDs of the categories chosen in the field separated by pipe. For example: `alpha|beta|charlie`. If only a single category is selected, then its output would be that category ID.
`{my_category_field:category_names}`\
This will list all the IDs of the categories chosen in the field separated by pipe. For example: Alpha`|Beta|Charlie`. If only a single category is selected, then its output would be that category ID.
All tag modifiers above support the `separator=","` parameter where you can change the pipe separator to another character of your choice. For example`{my_category_field:ids separator=","}` will output `1,2,3`
If you wanted to see if an entry is assigned to a category you can use a simple conditional:
```
{exp:channel:entries}
{title}
{if my_category_field:ids ~ "/(1|2|3)/"}
This entry is assigned to either category 1, 2 or 3
{/if}
{/exp:channel:entries}
```
# FAQs
{% hint style="danger" %}
Advanced Categories has been deprecated and is no longer for sale or supported. ExpressionEngine 7.4 introduces many of Advanced Categories features as natively to ExpressionEngine.
{% endhint %}
### Why would I need Advanced Categories?
Just like a lot of add-ons Advanced Categories is not required for every site, but some sites need more control over how categories are assigned to entries, and ExpressionEngine's native category fields do not have any rules around category selection. Also, as your site ages, its possible that some categories become deprecated, or category usage changes.
For example, maybe you don't want any new entries to be assigned to certain categories or category groups, but have hundreds or thousands of old entries where those category assignments are still relevant.
Another example, maybe your category groups make sense and are still used to display content on the front-end, but you only want the user to be able to assign a single category from one of two or more category groups. Advanced Categories lets you create a custom field with a single list of categories from multiple groups, and limit it to a single category selection.
With Advanced Categories you can customize which categories, from any group, are presented to an user when editing an entry. There are a lot of different reasons someone may want to drastically alter how categories are managed on an entry. Advanced Categories is designed to fit those needs.
### Does Advanced Categories replace the category groups on the entry publish page?
No, it does not replace the the Categories tab or the category group fields that appear on you rentry publish pages. Advanced Categories is a separate, standalone fieldtype that acts as a facade for assigning categories to an entry.
### What happens if I uninstall Advanced Categories?
Since Advanced Categories is just a custom fieldtype that acts as a facade for saving categories to an entry, uninstalling the add-on will not remove any assigned categories to any entries. Uninstalling it will simply revert the entry publish form to the state it was in before you installed it. If you're using the Advanced Categories custom fields in your front-end templates, such as `{primary_category:ids}` then obviously you'll need to remove the field tags from your templates.
### Wouldn't adding separate category fields to an entry publish page confuse editors?
Well, this is always a possiblity, but this is why it is **strongly** suggested to use the Publish Layouts feature in ExpressionEngine to either hide the default Categories tab entirely, or certain category groups. You can do this globally, or by user group, depending on what level of experience or knowledge your users have with the system. For Super Admin users, or highly experienced users maybe you want to keep the default Categories tab and category groups visible. For less experienced, or trusted users, hiding the default Categories tab and or category groups may be a better apporach.
### Is there a template tag to list categories?
If this is a question asking about a module template tag to replace the `{exp:channel:categories}` tag, then no. This is fieldtype only to assign categories to an entry. It is not, and will not, include any functionality to list categories outside of the context of a custom field.
### How do I display nested categories?
You can't, and there are no plans to support it. Since Advanced Categories lets you customize which categories are displayed, which means you can create more than 1 Advanced Categories field to display child relationships. Advanced Categories is intended to help *simplify* category display and selection. It is of our opinion that nested categories only complicate matters. Simple, flat category listing or bust :)
# Docs
# Installation
To install Ansel move the `/addons/ansel/` directory to your `/system/user/addons/` folder. Also copy the `/themes/user/ansel/` folder to the `/themes/user/` directory in your ExpressionEngine install. Login to your control panel and visit the ***Developer > Add-ons*** page, and click the Install link for Ansel.
# Upgrading
### If upgrading from Ansel 2.x to Ansel 3.x, the process should be seemless, but there are a few things to note.
{% hint style="warning" %}
The most noticeable functional change is that Ansel now only supports the native File Manager. The Assets and Treasury add-ons not longer work with Ansel. You can [read more about this decision in the FAQs.](/ansel/faqs)
{% endhint %}
In an effort to be more aligned with the native ExpressionEngine File Manager, the Caption field has been renamed to Description. When upgrading all field settings and database columns will be updated as such. If your template is using the `{img:caption}` variable it will still work. There is now an `{img:description}` tag.
Since Ansel and the native File Manager both have a Title and Description field, there is a new hidden config variable that when enabled will keep the two in-sync. This config value can be added or removed at any time (it defaults to 'n'), but if you add this to your config.php file prior to upgrading it will copy all the Title and Description field values from your Ansel files to the native File Manager. E.g. `$config['ansel_sync_meta_fields'] = 'y';`
{% hint style="info" %}
Not using the `ansel_sync_meta_fields` variable, or setting it to `n`, will make Ansel operate as it did in previous versions. Adding it will turn on the new metadata sync behavior.
{% endhint %}
Once an image is saved, the edit meta button will become available (screenshot below). Clicking this will let you edit the meta data of the cropped image, not the original source image. This lets you add a Title and Description that is unique to each usage. This is where you might want to decide if you want to keep the meta fields in-sync with the native FIle Manager. This does not change the front-end behavior when displaying images within an Ansel field. The syncing is mostly available for convenience and consistency. For example, if a content editor who isn't aware of how Ansel or the File Manager worked viewed a cropped image from within the ExpressionEngine File Manager, and chose to update the Title or Description fields it would not update the values of the image in the entry, and thus not reflect the changes on the front-end. However, if you enable syncing, the cropped image will be updated as well and the changes will be reflected on the front-end, and the next time the entry is viewed and edited.
If `ansel_sync_meta_fields` is enabled, then changes made to the Title and Description field in the image slide out will update the the Title and Description in Ansel. Conversely, if the Title or Description is updated in the Ansel field, and the entry is saved, then the Title and Description field in the slide out will also be updated. These are separate fields stored in separate database tables, only when `ansel_sync_meta_fields` is enabled will they be kept in-sync.
# Migrating from Assets
If you are using the Assets module to manage files, and want to switch to ExpressionEngine's native File Manager by changing the Upload, Save, and Preview folder settings in an Ansel field you will need to run a migration command, which will update the file IDs in the `exp_ansel_images` table.
**Please backup your database prior to running this command.**
In this example change `4` to whatever upload directory ID that Assets and Ansel are using. Run the command for each directory you need to update.
```bash
php system/ee/eecli.php ansel:migrate-assets --dir=4
```
# Requirements
* ExpressionEngine 7.4 or greater
* Using native File Manager (compatibility mode on or off)
* PHP 8.2 or greater
* GD (or GD 2) library. ImageMagick is also supported if installed.
* At least 256 megabytes of memory allocated and available to PHP
* 512 megabytes is recommended (and more if you can spare it). Manipulating images can take a lot of memory. And particularly, the larger image, the more memory it will take.
* `jpegoptim` for jpeg optimization
* `gifsicle` for gif optimization
* `optipng` for PNG optimization
# Settings
### Field Type Contexts
Ansel is compatible with the following contexts, and regardless of the context uses the same settings presented as uniformly as possible.
* [Channel Entries](https://docs.expressionengine.com/latest/control-panel/create.html)
* [Fluid Field](https://docs.expressionengine.com/latest/fieldtypes/fluid.html)
* [Grid](https://docs.expressionengine.com/latest/fieldtypes/grid.html)
* [Bloqs](https://boldminded.com/add-ons/bloqs)
* [Pro Variables](https://docs.expressionengine.com/latest/add-ons/pro-variables/overview.html)
### Storage Locations
Ansel is compatible with ExpressionEngine's new File Manager added in version 7. It supports sub-folders or compatibility mode (no sub-folders). *Ansel 3.0 no longer supports Assets or the Treasury modules.* ExpressionEngine's new File Manager is extremely robust and is the recommended path forward for the best experience. [You can read more about this change in the FAQs.](/ansel/faqs)
Ansel's Field Settings
***
### Upload, Save, and Live Preview Locations
The first two settings for any Ansel field are very related and require a tiny bit of explanation.
The Upload directory is where source images are drawn from or uploaded to. It is meant to be a user facing directory — the one your users will see when they add an image to an Ansel field.
The Save directory is where Ansel saves images the user crops or otherwise adds to the field. The end user should not ever need to see this directory. Ansel names the files with image IDs and timestamps for cache breaking purposes and so on when the user updates the images in any field.
The Preview directory is where Ansel saves images when viewing an entry in Live Preview mode. The contents of this directory are temporary, and when an entry is saved the contents of the directory are deleted. You can use the same directory for all Ansel fields, or create a unique directory for each field. If a user previews an entry and does not save it, then the images will not be deleted, and this is fine. The next time any entry using an Ansel field is saved the previous preview images will be removed even if they are not used in the entry.
{% hint style="info" %}
There are a few different approaches and ways of thinking about this. You could create a source and save directory for each field and keep everything separate, or you could create one general upload directory for all source images, and a save directory for each field. Either approach has its merits. Either way, it is highly recommended that you create a save directory for each field you create. This allows you to keep your images well segregated and create unique image manipulations per directory and field as well.
{% endhint %}
#### Tile View
Tile View is the new default layout introduced in Ansel 3. It is a more compact view that is more mobile friendly and more subitble to fields that include a lot of images. Disabling it will revert to the legacy vertical table layout.
#### Min and Max Quantity
Each Ansel field can hold any number of images, and these settings allow you to define how few and how many images a field can hold.
If tile view is enabled, max is set to 1, and prevent uploads when max quantity is enabled, Ansel will be put into single image view mode, which automatically displays the meta fields if enabled and removes the ability to toggle their display. The Cover metafield will also be disabled. If you're displaying only 1 image then there is no group of images it needs to be differentiated from as a cover.
#### Image Quality
Set the JPEG quality from 1 to 100.
{% hint style="info" %}
It is not normally a good idea to set the quality to 100. Anywhere from 70 to 90 is usually a good area to be in terms of quality vs. file size.
{% endhint %}
#### Force JPEG
Normally, image files are manipulated and saved in their original format. However, if you want all images to be saved as JPEG, you can specify so with this setting.
#### Retina Mode
When set to yes, the dimensions you enter for min/max width/height below will all be doubled. This allows you to set dimensions based on how you would think or normally specify dimensions in CSS, but doubles those dimensions so that your images will be retina ready.
#### Min/Max Width/Height
Use these fields to define image dimension requirements. Ansel will ensure that the image the user selects is at least as large as the minimum dimensions specified and that they cannot select a crop smaller than that. And Ansel will resize the image to meet the maximum specified size if the user selects a crop are that is larger than specified.
#### Crop Ratio
Enter a crop ratio to make sure the image is constrained to a certain aspect. The ratio is entered as 16:9, where the first number on the left side of the colon is the width of the ratio, and the number on the right side of the colon is the height of the ratio.
#### Named Crop Variants
Version 3.2 adds named crop variants with per-field crop definitions that let editors set independent crop regions for different viewports or display contexts. Each variant produces its own image file and is exposed as template variables and a ready-made `` tag.
#### Display Fields
There are three optional fields that can be set to show or hide, required, and the label of the fields can be customized. The title and caption fields are text input fields, and the cover field is a checkbox. Only one can be selected per field.
### Config File Settings
Ansel has some settings that are only controlled via the `config.php` file.
Disabled by default, but if you want the Title and Description meta fields in Ansel to stay in sync with the Title and Description field in the File Manager enable this setting.
```php
$config['ansel_sync_meta_fields'] = 'y';
```
Ansel defaults to ImageMagick, then uses GD if ImageMagick is not available. If you have both installed on your server and want to use GD instead, then you'll need add this to your `config.php` file
```php
$config['ansel']['forceGD'] = 'y';
```
If you're using image manipulations and optimizations you can optionally display any errors that might occur when performing these actions.
```php
$config['ansel']['optimizerShowErrors'] = 'y';
```
# Usage
### Getting To Know Ansel
Ansel will feel very familiar to use in the publishing workflow because it builds on the basic ExpressionEngine control panel styles.
There are two options for getting an image into your field:
* Drag and drop an image to the drop area or click it to select an image to upload
* Choose an existing image in the file manager (or use the file manager to upload an image)
One of the advantages to using the drag and drop interface is the image will never be uploaded if it does not meet requirements — whereas if you go through the file manger interface and upload from there, the image will be uploaded by EE then evaluated by Ansel.
Tile view with meta fields toggled
### Adding Images
When you drag and drop an image over the upload area in a field (or choose one from the existing images in the file manager), Ansel will automatically select the largest portion of the image possible given the constraints set up for the field and add an image row.
You can use the re-order handles to change the order of the images in the field.
To change the selected area and/or crop of the image, click the image thumbnail which will bring up the cropping interface with a lasso to select the relevant portion of the image. When you have selected the area of the image you want, click the green check mark or press the enter key.
If you wish to cancel the crop operation, click the red X, or press escape.
### Using metadata fields
Title, Description, and Cover fields are optional metadata that can be enabled in the field's settings. Ansel saves these values into it's own table along with the cropped images, but it also sync's the Tile and Description fields to ExpressionEngine's native Files storage. The Cover field has no equivalent in ExpressionEngine, so it is not synced. If you use the `ansel_sync_meta_fields` config value this will be a two way sync. Read more about this in the [Upgrading guide](/ansel/docs/upgrading).
# Channel:Form
Ansel works in channel:form, however you will notice that it will appear largely unstyled. This is because it relies on many styles and icons normally found within ExpressionEngine's control panel, but are not easily available on the front-end.
Including the following css file, per the channel:form docs, is not sufficient.
```html
```
You can include the entire `common.min.css`file, which is what is used by ExpressionEngine in the control panel, but it may apply more styles than necessary. If you include this you will notice that the Ansel field displays its missing styles.
```html
```
If you're using the legacy grid view in Ansel, you will not need to include the `common.min.css` file, it still renders most of it's styles.
**Ultimately it is up to you how to render the Ansel field in a channel:form. A little extra work to add custom styles may be necessary if you do not want to include `common.min.css`.**
We do recommend hiding the meta edit button since the slide out modal normally find when inside of the ExpressionEngine control panel is not available in channel:form tags.
```css
.js-ansel-edit-meta { display: none; }
```
# Troubleshooting
If you're encountering an issue with Ansel take these steps before submitting a support ticket.
## Check the Developer logs
Ansel 3 does a bit more logging of potential error messages than previous versions of Ansel. If you're encountering an issue hopefully it is getting logged. Please share the log messages when reporting an issue if they are available.
### Missing rendered images
If an image is not rendering (it is returning a 404) but it has a URL there are a couple things you can check. In your're using the `:resize` modifier in your Ansel tags the Ansel Saves folder should contain an `_ansel_image_cache` folder. If there is not then the Saves folder may not be writable or someone or something deleted the `_ansel_image_cache` folder. If the `_ansel_image_cache` folder exists but you do not see the resized image in that folder then you should check the `user/cache/ansel_persistent` directory. In an effort to reduce overhead and unnecessary image generation Ansel creates a simple text cache file in the `user/cache/ansel_persistent` directory that correlates to the usage of an Ansel field or module tag. Delete all the contents of the persistent directory, then try reloading the page containing your Ansel tags. If this was the issue you were experiencing then your resized images should be regenerated and display as expected.
### Using in Channel Form
Ansel does not currently work in `channel:form` tags. As far as we can tell this is not an an issue with the new 3.0 version. The old 2.3.4 version also does not work in `channel:form` tags in ExpressionEngine 7.5.x. It appears something has changed in ExpressionEngine that affects Ansel's usage in `channel:form` tags but we have not found a fix.
# Template Tags
The tag pair is how you output Ansel images. Whether you are using the custom field tag within a Channel Entry tag pair, a Grid field tag pair, a Bloqs field tag pair, a Low Variables tag pair, or the stand alone tag pair, usage is almost identical across the tags. In fact, the only real difference is with the stand alone tag pair, which has just a few extra parameters available to it.
```html
{exp:channel:entries channel="my_channel"}
{my_ansel_field count="true"}
{if "{my_ansel_field count='true'}" > 0}
{/if}
{my_ansel_field}
{img:url}
{img:picture_tag}
{/my_ansel_field}
{grid_field}
{grid_field:my_ansel_field}
{img:url}
{/grid_field:my_ansel_field}
{/grid_field}
{my_relationship_field}
{my_ansel_field}
{img:url}
{/my_ansel_field}
or
{my_relationship_field:my_ansel_field}
{img:url}
{/my_relationship_field:my_ansel_field}
{/my_relationship_field}
{my_relationship_field}
{my_relationship_field:child_relationship_field}
{my_ansel_field}
{img:url}
{/my_ansel_field}
{/my_relationship_field:child_relationship_field}
{/my_relationship_field}
{blocks_field}
{my_block}
{my_ansel_block_field}
{img:url}
{/my_ansel_block_field}
{/my_block}
{/blocks_field}
{/exp:channel:entries}
{exp:low_variables:pair var="my_ansel_var"}
{img:url:resize width="500"}
{/exp:low_variables:pair}
{exp:ansel:images content_id="102" field_id="33"}
{if img:no_results}
{/if}
{img:url:resize width="400"}
{/exp:ansel:images}
```
### Tag Pair Parameters
```php
image_id="104|105"
not_image_id="106|110"
site_id="2"
not_site_id="1"
file_id="2|3" // EE file id
not_file_id="18|27"
original_location_type="ee|assets" // Possible values: ee|assets|treasury
not_original_location_type="treasury|ee"
original_file_id="34|45"
not_original_file_id="45|56"
upload_location_type="assets|treasury" // Possible values: ee|assets|treasury
not_upload_location_type="ee|assets"
upload_location_id="34|45"
not_upload_location_id="45|56"
filename="my_file" // do not include extension
not_filename="foo"
extension="jpg"
not_extension="jpg"
original_extension="png"
not_original_extension="png"
filesize="182827"
filesize="< 182827"
filesize="> 182827"
original_filesize="182827"
original_filesize="< 182827"
original_filesize="> 182827"
width="300"
width="< 300"
width="> 300"
height="300"
height="< 300"
height="> 300"
title="my title|my other title"
not_title="foo|baz"
description="my description|my other description"
not_description="foo|baz"
member_id="23|24"
not_member_id="56|23"
position="2"
position="< 2"
position="> 2"
cover_only="true"
skip_cover="yes"
show_disabled="y"
namespace="my_namespace" // Access variables as {my_namespace:var}
limit="4"
offset="4"
order_by="date:desc|order:asc"
random="yes" // Overrides order_by parameter
cover_first="yes"
manipulations="true" // Include EE directory manipulations (requires extra queries)
host="https://cdn.domain.com/"
```
The following parameters are unique to the stand-alone image tag:
```php
not_source_id="45|46"
content_id="34|36" or entry_id="34|36" // Usually the entry id, but could be low variables id
not_content_id="46|68" or not_entry_id="34|36"
content_type="channel|grid" // Possible values: channel|grid|blocks|low_variables
not_content_type="low_variables|channel"
field_id="23|26" or field_name="foobar"
not_field_id="45|56" or not_field_name="foobar"
row_id="32|33" // Grid or Blocks
not_row_id="444|745"
col_id="43|44" // Grid or Blocks
not_col_id="5|10"
```
### Tag Pair Variables
Note all variable examples assume the default namespace of img. Use your custom namespace if you have set the namespace parameter.
These variables are available in the tag pair:
```html
{img:id}
{img:site_id}
{img:content_id}
{img:field_id}
{img:content_type}
{img:row_id}
{img:col_id}
{img:file_id}
{img:original_file_id}
{img:upload_location_id}
{img:filename}
{img:original_filename}
{img:basename}
{img:original_basename}
{img:extension}
{img:original_extension}
{img:filesize}
{img:original_filesize}
{img:width}
{img:height}
{img:title}
{img:caption}
{img:caption_raw}
{img:description}
{img:description_raw}
{img:member_id}
{img:position}
{img:cover}
{img:upload_date}
{img:modify_date}
{img:path}
{img:original_path}
{img:url}
{img:original_url}
{img:thumbnail_path}
{img:thumbnail_url}
{img:index}
{img:count}
{img:total_results}
{img:host}
{img:description_field}
{img:credit_field}
{img:location_field}
{img:original_title_field} or {img:original_title}
{img:original_description_field} or {img:original_description}
{img:original_credit_field} or {img:original_credit}
{img:original_location_field} or {img:original_location}
```
The variables starting with "original" reference the value from the source file. When Ansel saves an image, it creates a new instance of that image in your file manager (wether it was cropped or not). Each instance of a file can have it's own description, caption, title etc. If you want to always reference the original description, regardless of which cropped version you're displaying in the template, you can use a conditional. For example:
```
{if img:original_description}
{img:original_description}
{if:else}
{img:description}
{/if}
```
When you have made manipulations available with the parameter `manipulations="true"`, they will be available as follows:
```html
{img:manipulation_name:path}
{img:manipulation_name:url}
{img:manipulation_name:width}
{img:manipulation_name:height}
```
### No Results
If your tag pair has no results, you can use the `{if img:no_results}` conditional to output content.
### On the Fly Cropping and Resizing
Ansel can crop and resize images on the fly. Doing so is very efficient because the cropped/resized image is cached after the first request for it is made. Any request for that cropped/resized image thereafter comes straight from the cache on disk.
Cropping/resizing is available to the `{img:url}` variable.
```php
width="400"
height="100"
crop="true"
background="d34747"
force_jpg="true"
quality="80"
scale_up="true"
cache_time="86400" // Defaults to forever
```
```php
{img:url:resize
width="400"
height="100"
crop="true"
background="d34747"
force_jpg="true"
quality="80"
scale_up="true"
}
```
### Get Total
Sometimes you would like to display the total number of images in a field. Ansel makes this really easy with a parameter on the custom field tag:
```php
{exp:channel:entries channel="my_channel"}
{my_ansel_field count="true"}
{/exp:channel:entries}
```
### Picture Tag
#### `{img:picture_tag}`
Outputs a complete `` element. Only named crops with a **Media Query** value are included as `` elements. The fallback `` always uses the main crop (`{img:url}`).
Example output:
```html
```
**Tag Parameters**
| Parameter | Default | Description |
| --------------------- | -------- | ------------------------------------------------------- |
| `picture_tag_loading` | `lazy` | Value of the `loading` attribute on the `` element |
| `picture_tag_class` | *(none)* | CSS class applied to the `` element |
Example:
```ee
{ansel_field picture_tag_loading="eager" picture_tag_class="hero-image"}
{img:picture_tag}
{/ansel_field}
```
***
### Config Variable Substitution in Media Queries
Media query values in the field settings support `{config_key}` placeholders that are resolved at render time from EE's `$config` array. This avoids hard-coding breakpoints in the database and makes them easy to update site-wide.
**In `config/config.php`:**
```php
$config['bp_small'] = '(max-width: 767px)';
$config['bp_medium'] = '(min-width: 768px)';
$config['bp_large'] = '(min-width: 1200px)';
```
**In the field settings Media Query column:**
```
{bp_large}
{bp_medium}
{bp_small}
```
At render time these resolve to their config values. Unrecognized placeholders are left as-is so typos are immediately visible in the rendered HTML.
### Twig/Blade
If you're using [Coilpack](https://expressionengine.github.io/coilpack-docs/docs/), Ansel supports Twig and Blade templates. All of the same parameters from the EE Template examples above are also available in Twig or Blade.
{% tabs %}
{% tab title="EE Template" %}
```html
{exp:channel:entries
channel="pages"
dynamic="no"
}
{% for row in entry.my_ansel_field %}
{{ row.url }}
{{ row.title }}
{{ row.description }}
{{ row.file_id }}
{% endfor %}
{% else %}
No entries found
{% endfor %}
```
{% endtab %}
{% tab title="Blade" %}
Example coming...
{% endtab %}
{% endtabs %}
# Publisher Support
If you're using Ansel and Publisher, you will also need this extension:
# FAQs
### Does Ansel support the Assets field type?
No, version 3.0 removed support for Assets. It only supports the native File Manager. Simply updating the Ansel field settings to point to the same EE file directory as an Assets folder will not work. The ExpressionEngine team has been working on an Assets to native File Manager migration tool, which will be released soon. For this reason, we've decided to end support for the Assets field and recommend using the migration tool when it becomes available. Assets, while being a great add-on, has become less important when building ExpressionEngine sites now that the native File Manager supports sub-folders, and remote (e.g. S3) file services. So in an effort to keep things moving forward, and to simplify the Ansel codebase, we've decided not to support Assets.
### Does Ansel support Treasury?
No, version 3.0 removed support for Treasury, for much the same reason as removing support for Assets.
### Does Ansel work in channel:form tags?
Ansel does not currently work in `channel:form` tags. As far as we can tell this is not an an issue with the new 3.0 version. The old 2.3.4 version also does not work in `channel:form` tags in ExpressionEngine 7.5.x. It appears something has changed in ExpressionEngine that affects Ansel's usage in `channel:form` tags but we have not found a fix.
# Docs
# Why Bloqs?
Bloqs is like a Fluid field, but on steroids. It gives you the freedom to build robust repeatable content modules using the [atomic design pattern](https://bradfrost.com/blog/post/atomic-web-design/). Functionally Bloqs shares more similarities with ExpressionEngine's native Grid field. Every row in the Grid field has the same custom field options because they all share the same columns. Think of Bloqs as a Grid field where each row has different columns, and you can place the rows in any order you want.
If a Grid field has rows and columns, then a Bloqs field has bloqs and atoms. You create a bloq, then add one or more custom fields (aka atoms) to it, and then assign that bloq to one or more custom fields in a channel. Unlike the native Fluid field, since a single bloq contains multiple custom fields, those fields can work in conjunction with each other. One field can contain your text, the other one might be a select menu determining how that text is displayed. If you're using [nested bloqs](/bloqs/docs/features/nesting), the fields within a single bloq can be even more powerful as their values can cascade down to child bloqs.
# Features
This section highlights some important features in Bloqs
# Add Bloq Menu
When managing a bloq definition, you can optionally assign the bloq to a group that you define. If a bloq is not assigned to a group, it is considered "Ungrouped", which is the default.
By default, the Add Bloq menu will display as a vertical list. If no additional Bloq Groups are defined, then bloqs will not be organized by group in the Add Bloq menu.
### Add Menu Grid
When editing the Bloqs field from the *Channel > Fields* menu there is an option to display the Add Bloq menu as a grid. This will organized bloqs by groups (if defined) to a 3 column layout, and also display a choosen image or icon with the bloq. The image or icon can be used to help visually identify what type of bloq it is.
### Preview Image or Icon
When displaying the Add Bloq menu as a grid, you can assign an image or icon to the bloq. The Image field uses ExpressionEngine's native File Manager, so you can add any image you want. It is recommended to keep your image in the 50x50 pixel dimension. You can also use one of the existing Icons from the Font Awesome library that is available through ExpressionEngine. **The Preview Icon field is only available in ExpressionEngine 6 or greater.**
# Nesting
With Bloqs you can create true heirarchial relationships with your content, and have them render as such in your templates. To start nesting just enable it on the field, and add an additional closing tag pair to each bloq as mentioned below.
Some basic nesting rules are also available that can be applied to each bloq.
* Can be nested at any level
* Can only be at the root
* Can't be root and must be a child of another bloq
* Set a bloq as must be a child of another bloq by selecting 1 or more possible parent bloqs
* Set a bloq is allowed to have child bloqs
* Set a bloq as having a minimum, maximum, or exact number of child bloqs
While editing your bloqs you may see warning messages when one of these rules is violated, however, Bloqs will not stop an entry from saving if a nestable tree is invalid based on the rules you defined. It is up to the content editors to ensure the nesting is valid before saving an entry (no warning messages means it is valid). If an invalid bloq tree is saved, the bloqs will still be rendered in your templates, but they may not display as you expect them to based on nesting rules and the HTML and CSS defined for the bloq.
When nesting is enabled you can choose to add a new bloq as an immediate child of the current bloq. Use the "Add bloq as child" to avoid excessive drag and drop of bloqs to build a nested structure. When nesting rules are applied, the menu respects those rules and will not let you insert a bloq where it does not belong.
### Enabling Nesting
All Bloqs fields default to the old sortable behavior. You must enable nesting on each field. If you want to use Bloqs, but don't need the nesting functionality, just don't enable the option and continue using Bloqs like you always have (you won't need the closing tag pair mentioned below).
### Variables
If nesting is enabled, each bloq contains a few new variables:
```
{bloqs:parent:id}
{bloqs:parent:shortname}
{bloqs:children:total_bloqs} or {bloqs:children:total_rows}
{bloqs:siblings:total_bloqs} or {bloqs:siblings:total_rows}
```
### Template Tags
When nesting is enabled, the templates expect that each bloq have its own `{bloqs:children}` tag. This tag will render all child bloqs of the current bloq recursively.
```
{bloqs_field}
{section_bloq}
{heading_atom}
{bloqs:children}
{/section_bloq}
{row_bloq}
{/row_bloq}
{/bloqs_field}
```
{% hint style="warning" %}
The following documentation about the `{close:*}{/close:*}` tag pairs was deprecated in version 4.6.0, and completely removed in version 5.0. For this reason, it is suggested to use the new `{bloqs:children}` syntax noted above.
{% endhint %}
When nesting is enabled, the templates expect that each bloq have its own closing tag. The contents of this tag will be moved to the appropriate location in the final template output to wrap child bloqs. If you create a "section" bloq that is the parent of several child bloqs, the closing content of the section bloq will be added after the child bloqs have been rendered to create a properly nested HTML structure. The closing tag is always the name of the bloq it is in, prefixed with "close:"
```html
{bloqs_field}
{section_bloq}
{heading_atom}
{close:section_bloq}
{/close:section_bloq}
{/section_bloq}
{row_bloq}
{/close:row_bloq}
{/row_bloq}
{/bloqs_field}
```
If you have templates using the old {close} tag syntax, here is an example of how the previous example would be updated to use {bloqs:children}.
```html
{bloqs_field}
{section_bloq}
{heading_atom}
{bloqs:children}
{/section_bloq}
{row_bloq}
{/row_bloq}
{/bloqs_field}
```
### Bloq Variables
When a field is nestable, you have the option of prefixing your atom short names with `bloq_var_`. If an atom name has this prefix its value will be passed down to all child bloqs. The next bloq that contains the same atom at the same nesting depth, or higher, will have a new value, and thus pass it down to its children. In the example below the `{bloq_var_columns}` atom is defined on the Row bloq, which means its value is available in the Row bloq itself, and the Basic Content and CTA bloqs that are children of Row. Bloq variables only work with basic atom fieldtypes such as text, radio, or checkbox fields (or any fieldtype that outputs a simple string value). You can not use a Relationship field, or a 3rd party field such as Assets or Ansel as bloq variable.
If you use a `bloq_var` in a conditional, you will need to quote it, e.g. `{if '{bloq_var_columns}' > 2}`
### Example Code
The following example code is used in [this video demo](https://vimeo.com/251749666).
```
{bloqs_field}
{section}
{heading}
{summary}
{bloqs:children}
{/section}
{row}
{heading}
{bloqs:children}
{/row}
{basic_content}
{heading}
{body}
{bloqs:children}
{/basic_content}
{cta}
{heading}
{bloqs:children}
{/cta}
{/bloqs_field}
```
Another option to display child bloqs that was introduced in verison 5.0, is to use the `{bloqs:child:[my_bloq_name]}` tags instead of `{bloqs:children}`, which automatically iterates all the child bloqs and renders them. This is useful for when you need the output of children bloqs to display in a certain way, regardless of the order in which the children appear when editing the entry in the publish page. For example, the above code could also be the following:
```
{bloqs_field}
{section}
{bloqs:child:cta}
{heading}
{summary}
{bloqs:child:basic_content}
{/section}
{row}
{heading}
{bloqs:children}
{/row}
{basic_content}
{heading}
{body}
{bloqs:children}
{/basic_content}
{cta}
{heading}
{bloqs:children}
{/cta}
{/bloqs_field}
```
# Cloning
Bloqs can be cloned when in nested and non-nested fields. If you're cloning a bloq in a nested field with child bloqs, all the child bloqs will also be cloned.
###
# Drafts
Bloqs can be set to draft, which means it will not display on the front-end when rendered in your templates. If you're marking a bloq as draft that has children, then all the children of the draft bloq will also not display on the front-end. In the animation below, the Section bloq is set to draft, but the child Basic Content bloqs are not. In this scenario the only bloq that would display on the front-end is the Slab bloq.
# Bloq Usage
Starting in Bloqs 4.4.0 you can get more insight into how your bloqs are being used. The bloq definition list now includes a new column that displays the number of entries the bloq is used in. The number displayed in this list is the total usages of the bloq across all Bloqs fields it is assigned to. Clicking the link will display a list of entries and links to edit each entry.
Also starting in version 4.4.0 is that once a bloq exists in any entry, the checkbox on the Bloqs edit field where you assign which bloqs are available to the field, are disabled. Prior to 4.4.0, if you uncheck a bloq on this page and save the custom field, any entries that contained that bloq had it's bloqs removed, thus causing a potentially unintended data loss. If you need to remove a bloq assignment from a field, it is best to use the usage links on the right to find the entries the bloq is used in, edit the entries, then remove the bloq assignment. The usage links on this page show the total entries the bloqs are used in this field only, not a cumulative count like on the bloq definition list above.
If you want to disable this feature and return to pre-4.4.0 behavior, you can use the `bloqs_disable_strict_assignment` [hidden config variable](/bloqs/docs/configuration/hidden-config-options).
# Deprecated Bloqs
Starting in Bloqs 4.4.0 you can assign the "Deprecated" status to a bloq. As your site evolves you may need to update certain bloqs, and in some cases retire them all together. Simply deleting the bloq may cause data loss and existing pages to break. To avoid that you can gracefully deprecate your bloqs. When you assign a deprecated status the bloq all existing instances of the bloq will continue to function as expected on the front-end, and in the control panel, but content editors will no longer see the bloq in the Add Bloq menu, thus they can't create new instances of a deprecated bloq. To make a bloq deprecated, just toggle the *Deprecated?* setting on the bloq. You can also add a short note that will appear in all existing instances of the bloq to inform content editors of its new status. If you do not add a deprecated note, Bloqs will simply display "This block is deprecated".
{% hint style="info" %}
Setting a bloq to deprecated **does not prevent saving an entry** that contains deprecated bloqs. Deprecation is just a visual warning meant to nudge content editors to update or remove the bloqs with whatever direction you provide them, and prevent them from adding additional deprecated bloqs to an entry.
{% endhint %}
When a bloq is deprecated, it will have a warning icon next to its name in the bloq definition list. This way you can easily tell which bloqs are deprecated.
When a Bloqs field has 1 or more deprecated bloqs, a warning appears above the field informing the content editor of the issue. Deprecated bloqs are again noted with a warning icon and a note.
# Caching
### Field Caching
Bloqs offers field caching, which will cache the final output of a single Bloqs field in a template. Enabling caching will decrease page load time by rendering cached content, thus avoiding the additional parsing necessary to render all the custom field data from the atoms inside each bloq.
Bloqs is a complicated add-on. If you have an entry with a Bloqs field that has 10 bloqs, and each bloq has 5 atoms (custom fields), you're effectively rendering 50 fields to in a template. If each of those 10 bloqs has a Relationship field, then you're rendering 10 Relationship fields on the front-end of your site. These complicated field types (any fieldtype that is not a basic text, textarea, wysiwyg, radio, checkbox etc) can add considerable overhead. Below is an example of a profiling output from a cached and uncached Bloqs field render:
```
# Uncached rendering time in seconds
Bloqs Replace Tag: 3.1513
# Cached rendering time in seconds
Bloqs Replace Tag: 0.0086
```
When an entry is saved, the corresponding cache item will be deleted. The next time the field is rendered on the front-end, a fresh cache item will be created.
```
$config['bloqs_cache_enabled'] = true;
```
When displaying a cached Bloqs field on the front-end, it will be wrapped in the following html comment tags:
```
... Your bloqs content here ...
```
{% hint style="info" %}
The only way to clear a cached item is to re-save an entry, or clear the cache manually. If a site is actively being developed, it is probably best to not enable caching because making changes to template files will not clear the cache, thus you may not see the most up-to-date content. Enable cache in production sites only.
{% endhint %}
# Profiling
If ExpressionEngine's profiling is enabled, you will see additional entries in the Performance tab in the output profiler at the bottom of the page. Example output:
```
Bloqs Render Bloq #529874/Theme: 0.0002
Bloqs Render Bloq #529993/Locale: 0.0002
Bloqs Render Bloq #529993/Theme: 0.0002
Bloqs Render Bloq #529996/Locale: 0.0002
Bloqs Render Bloq #529996/Theme: 0.0002
Bloqs Render Bloq #530006/Locale: 0.0002
Bloqs Render Bloq #530009/Links: 0.0308
Bloqs Render Bloq #530010/Content: 0.2050
Bloqs Render Field #631: 2.6799
```
In this example, the pattern `#[bloq id]/[atom name]` is followed by the total time it took the server to parse the full value of the field to a string, which is inserted into the template. With this information you can identify potential bottlenecks in your Bloqs fields. The very last line `Bloqs Render Field #631` is an example of the total time it took Bloqs to render the output for the entire custom field.
# Bloq Components
*Added in version 4.6.0 as Bloq Templates*\
*Renamed in version 4.8.0 to Bloq Components*
{% embed url="" %}
Bloq components are designed to do two things:
1. Speed up content management by building pages quicker.
2. Give you, the developer or designer, more control over how content is created.
As a developer, you can create a component that is collection of bloqs that can be added to an entry with a single click. Most sites have re-usable content patterns. Simple patterns can be built using a single bloq, but bigger, or more complex patterns, may require the uses of several bloqs. Some patterns may share bloqs as well. By using a bloq component, you can pre-build these re-usable patterns. Components do not allow pre-populating of content, just the definition of the component itself. If you're familiar with atomic design, each bloq is the equivalent of a [molecule](https://bradfrost.com/blog/post/atomic-web-design/#molecules). A single bloq consists of multiple atoms, or fields. Bloq components, on the other hand, let you define a [template](https://bradfrost.com/blog/post/atomic-web-design/#templates), or an [organism](https://bradfrost.com/blog/post/atomic-web-design/#organisms).
{% hint style="info" %}
Bloq components do not require you to change your front-end template file code. You can start using bloq components on existing sites using bloqs you already have defined. Just create a new bloq and set it to a component, and assign bloqs that you want to use within the component. Those same bloqs can still be added separately to a field as long as they're selected in the field's settings.
{% endhint %}
### Editable Components
When an editable component is inserted into an entry, it inserts multiple bloqs just like if you had inserted each bloq individually, except it inserts them all at once. The content editor can than remove, clone, or re-order those bloqs just as they could any other bloq. This also means they can choose to not use the design pattern that you have put in place. In some cases this may be desired. An editable component is useful for common, but flexible, content patterns. Since they can be modified they do not have a unique visual appearance like a non-editable component.
### Non-Editable Components
A non-editable, which is the default state, component means that when the component is inserted into an entry, none of the bloqs within the component can be removed, cloned, or re-ordered. The component is fixed, and will always present itself that way. This is the strictest use of a bloq component. After all you created the component for a reason. It has a pre-defined and expected structure, and you always want it to appear this way without any modifications.
### Bloq Components and non-nested fields
If you create a bloq component and you assign it to a Bloqs channel field that is not set to nestable, the field will automatically be set to nestable. If you disable the nestable setting on the Bloqs channel field and save an entry containing bloq components, then the nesting structure will be lost and your bloqs will flatten out, thus affecting the presentation on the front-end and within the control panel.
# Bloq Groups
Bloq groups are a way to organize your bloqs into logical groups. If you have several bloqs that create social media content, *Social Media* may make a good group name. Groups are only used in the add bloq menu inside the control panel when editing an entry. If no groups are created, the bloqs will be displayed in the order you define on the channel field edit page where you assign bloqs to a field. If a bloq is added to a group, then the display order in the add bloq menu will be based on the *Order* field of the group, then the order field of the bloqs within that group. If no groups are defined, then no groups will be displayed in the add bloq menu. If groups are defined, but some bloqs are not assigned to a specific group, then they will be added to an *Ungrouped* group at the bottom of the menu.
# Import & Export
Bloqs 5.5 lets you export selected bloq definitions to a JSON file and re-import them into another ExpressionEngine site. Use it to move bloqs from local to production, between staging sites, or to share a set of bloqs with another project. Only the definitions are exported (the bloq types, their fields, settings, nesting rules, and component structure). Entry content is never exported; it stays in the entries on each site.
{% hint style="warning" %}
BoldMinded is not responsible for data loss when using this feature.
**Backup your database before running imports.**
{% endhint %}
### Exporting
On the **Bloqs** listing screen, each row has a checkbox. Select one or more definitions, choose **Export** from the bulk-action bar that appears, and submit. Your browser downloads a JSON file named `bloqs-definitions-N.json`.
The export is self-contained and human-readable. Because the receiving site won't share the same database IDs, every cross-reference is rewritten into a portable form:
* **Bloq groups** are exported by name.
* **Nesting rules** ("can be a child of...") are exported as shortnames.
* **Component child bloqs** are referenced by shortname.
#### Example export
```json
{
"bloqs_export_version": 1,
"source": {
"bloqs_version": "5.5.0"
},
"block_definitions": [
{
"shortname": "hero",
"name": "Hero",
"instructions": "A full-width hero banner.",
"group": "Layout",
"deprecated": 0,
"deprecated_note": "",
"preview_image": "",
"preview_icon": "image",
"is_component": 0,
"is_editable": 0,
"settings": {
"nesting": {
"root": "any",
"child_of": ["section"],
"no_children": "y"
}
},
"atom_definitions": [
{
"shortname": "headline",
"name": "Headline",
"instructions": "",
"order": 0,
"type": "text",
"settings": { "field_fmt": "none", "col_required": "y" }
},
{
"shortname": "related",
"name": "Related Entry",
"instructions": "",
"order": 1,
"type": "relationship",
"settings": { "channels": ["3"], "authors": [], "limit": "1" }
}
]
}
]
}
```
A **component** bloq also carries a `component_children` array listing the child bloqs by shortname along with their tree position (`order`, `depth`, `parent_id`, `lft`, `rgt`, `cloneable`).
The `bloqs_export_version` field is the format version. A site running an older version of Bloqs refuses a file whose version is newer than it understands.
### Importing
Use the **Import** screen to upload an exported file. You upload the file and choose options, then see a preview of exactly what will happen. Nothing is written until you confirm.
#### The import options
**Definition File** (required): the JSON file you exported.
**Preserve Site-Specific Settings** (off by default): when off, field settings that reference site-specific IDs are reset to safe defaults. Turn it on only when the target site shares the same channel, upload-directory, and field IDs as the source, such as a local-to-production sync of the same site. See "The site-specific settings rule" below.
**Update Existing Definitions** (off by default): when off, a matching shortname is imported as a renamed copy. When on, matching bloqs are updated in place. See "Adding vs. updating" below.
**Remove Atoms Not In File** (off by default, only applies when "Update Existing" is on): deletes fields on the target that aren't in the file. This is destructive, since deleting a field also deletes its content in every entry that uses it. The preview shows which fields would be deleted and how many entries would lose content.
#### The preview
Before committing, you get a dry-run summary:
* **Will be created**: definitions that don't exist on the target.
* **Will be updated**: existing definitions updated in place (only when "Update Existing" is on).
* **Renamed to avoid collisions**: definitions whose shortname already exists and will get a numeric suffix.
* **Fields needing reconfiguration**: fields whose site-specific settings will be reset.
* **Atoms to be deleted**: fields that will be removed, each with the count of affected entries.
### The rules: adding, updating, deleting
#### Adding (the default)
With "Update Existing" off, every definition is created new. If a shortname already exists on the target (whether from another bloq or a native channel field), the imported copy gets a unique suffix: `hero` becomes `hero_2`, then `hero_3`. An import can never overwrite existing data this way; the worst case is a renamed duplicate. References within the import (nesting, component children) are rewired to point at the renamed copies.
#### Updating (opt-in)
With "Update Existing" on, a definition whose shortname matches one on the target is updated in place. This updates the bloq and its fields:
* The bloq's own properties (name, instructions, group, deprecation, preview image/icon, component flags, nesting settings) are overwritten from the file.
* Each field is matched by shortname within that bloq:
* A field on both is updated in place, keeping its existing database ID. Since entry content is tied to that ID, no content is lost.
* A field in the file but not on the target is created.
* A field on the target but not in the file is left untouched by default.
#### Deleting (explicit, destructive)
An import never deletes anything unless you ask. The only deletion path is **"Remove Atoms Not In File"**, available only in update mode. When enabled, fields on the target but absent from the file are deleted, and deleting a field cascades to its content in every entry. The preview lists each field with its entry-usage count. Whole definitions are never deleted by an import; to remove a bloq, use the delete action on the Bloqs listing (which is blocked while the bloq is in use).
### The site-specific settings rule
Some field types store references identified by site-local IDs: relationship fields point at channels, categories, statuses, and authors; file and Assets fields point at upload directories. These IDs are meaningless on a different site.
Unless "Preserve Site-Specific Settings" is on, the importer resets these references to safe empty defaults for the affected types (relationship, file, file\_grid, assets). The field is imported intact and usable, just unconfigured for those references, which you reconnect on the target. The preview lists every affected field. The rest of a field's settings (label, limits, required, formatting) are always preserved.
Turn this option on only when the target's IDs match the source's, typically a local-to-production sync of the same site.
### The `renamed_from` nuance
The importer matches definitions and fields by shortname. If you rename `headline` to `title` in the source and import with "Update Existing" on, the importer can't tell `title` is the old `headline`. It sees `headline` as gone and `title` as new, so it creates a new empty `title` and leaves the old field alone.
To handle a rename, add a `renamed_from` property by hand to that entry in the JSON before importing. It tells the importer: if you can't find my current shortname, look for this old one and update that record in place.
```json
{
"shortname": "title",
"name": "Title",
"type": "text",
"renamed_from": "headline",
"settings": { }
}
```
With this and "Update Existing" on, the importer finds the existing `headline` field, updates it in place (keeping its ID and all entry content), and changes its shortname to `title`. The same works at the bloq level: `"renamed_from": "hero"` with `"shortname": "hero_banner"` updates the existing `hero` bloq and renames it.
Notes on `renamed_from`:
* It's matched only as a fallback. The current shortname is tried first, so it's harmless to leave in a file you re-import.
* It's supplied by hand. Bloqs doesn't auto-detect renames or write `renamed_from` into exports, because the database keeps no rename history.
* It works safely with "Remove Atoms Not In File": a field matched via `renamed_from` has its old shortname treated as accounted for, so the remove step won't delete it.
Within a single site you never need `renamed_from`. Just rename the field in the control panel; content is tied to the field's ID, so nothing is lost. `renamed_from` exists only for cross-site imports, where the two sites share no ID and the shortname is the only stable key.
# Installation
To install Bloqs move the `/addons/bloqs/` directory to your `/system/user/addons/` folder. Also copy the `/themes/user/bloqs/` folder to the `/themes/user/` directory in your ExpressionEngine install. Login to your control panel and visit the ***Developer > Add-ons*** page, and click the Install link for Bloqs.
### Updating Blocks (for EE 2) to Bloqs (for EE 3+)
As a result of the Add-on name change, updating from Blocks (EE2) to Bloqs (EE53) is a tad bit misleading during one part of the process, but rest assured all will work out and you will be up and running in no time.
**Here’s what you’ll need to do:**
1. Upgrade your ExpressionEngine 2 installation to the latest version of ExpressionEngine 3. ([upgrading from EE2 to EE3](https://docs.expressionengine.com/v3/installation/upgrade_from_2.x.html))
2. [Download](https://devot-ee.com/add-ons/bloqs-blocks-for-ee3) the latest version of Bloqs
3. In the `/system/user/addons` directory of your (recently upgaded) ExpressionEngine installation, locate and delete the “blocks” folder. This is the old version of Blocks which is only compatible with EE2.
4. In the `/themes/user` directory of your ExpressionEngine installations, locate and delete the `blocks` folder.
5. Open up the Bloqs package you downloaded in Step 2, and move the `/system/user/addons/bloqs` folder into the `/system/user/addons` directory of your ExpressionEngine installation.
6. Move the `/themes/user/bloqs` folder into the `/themes/user` directory of your ExpressionEngine installation.
7. Now, login to your ExpressionEngine Control Panel and open up the Add-on Manager view.
8. (Here’s where things are a bit misleading). Locate ‘Bloqs’ in the Third Party Add-Ons list. You’ll notice that it’s grayed out with a button that says “Install” next to it. Don’t panic! If Bloqs was already installed on your EE2 site, it’s still there - you haven’t lost anything. Just click the button that says ‘Install.’
9. The Bloqs update routine will run and handle the Blocks to Bloqs conversion process.
10. That’s it, you’re all set to go!
# Requirements & Compatibility
Requirements
* ExpressionEngine 6.4 or greater
* PHP 8.2 or greater
* PHP `max_input_vars` set to a minimum of `2000`.
{% hint style="info" %}
Sites using a lot of bloqs and custom fields within an entry may want to consider increasing PHP's `max_input_vars` setting. Usually the default is 1000. Increasing it to 2000 or more may be required.
{% endhint %}
### Compatibility
**Native ExpressionEngine Fieldtypes**
* Checkboxes
* Date
* Duration
* Email Address
* File
* Multi Select
* Number Input
* Notes
* Radio Buttons
* Relationships
* Rich Text Editor
* Select Dropdown
* Selectable Buttons
* Text Input
* Textarea
* Toggle
* Value Slider
* URL
**Native ExpressionEngine Features**
* Entry Manager custom column (Bloqs must be set to searchable)
* Search
{% hint style="info" %}
Bloqs is built using the same concepts as the Grid field, and because Grids within Grids are not allowed, a Grid (and similarly File Grid) may not be placed within a bloq*,* however, you can use our [Simple Grids & Tables](https://boldminded.com/add-ons/simple-grids-tables) add-on for basic Grid functionality within Bloqs.
The native Fluid field type is also not supported by Bloqs.
{% endhint %}
#### Third-party fieldtypes & add-ons opted in to Bloqs
* [Ansel](https://boldminded.com/add-ons/ansel)
* [Assets](https://eeharbor.com/assets) (by [EEHarbor](https://eeharbor.com))
* [Expresso](https://www.putyourlightson.net/expresso) (by [Put Your Lights On](https://www.putyourlightson.net/))
* [Publisher](https://boldminded.com/add-ons/publisher-2) (by [BoldMinded](https://boldminded.com/))
* [Wygwam](https://eeharbor.com/wygwam) (by [EEHarbor](https://eeharbor.com))
* [Wyvern](https://addons.reinos.nl/wyvern) (by [Reinos](https://addons.reinos.nl/))
If you are unsure if an add-on works in Bloqs, but it works in Grid, then chances are it already works in Bloqs. There are a vast number of 3rd party fieldtypes not listed above that already work in Bloqs.
If your add-on/fieldtype is compatible with Bloqs and you don't see it in the list above, [send us a message](https://eebloqs.com/contact) and let us know!
### Performance
Bloqs is a robust and powerful add-on that adds a lot of flexibilty when building out your site content. Since you can add any number of bloqs to a single entry, keep in mind that the more bloqs you add, the more template parsing is required, and the longer it may take for a control panel page to load when editing an entry. For example, if you add 10 bloqs to an entry, and if each bloq has 5 atoms in it it, you're effectivley adding 50 custom fields to the entry. To mitigate this on the front-end you can use Bloqs' [built in caching option](/bloqs/docs/configuration/hidden-config-options#field-caching), or add full featured caching with [Speedy](/speedy/docs). In most cases caching won't be required, just keep performance in mind when planning and building your site with Bloqs.
# Setup & Configuration
After installing Bloqs the first thing you will want to do is create some bloqs! Below is a screenshot of the main Bloqs settings page. As you can see we have 7 bloqs already created, but after a new installation of Bloqs, this list will be empty.
Creating a bloq is easy. At the top of the page you give it a name and short name, as well as assign it to a group, preview icon or image, and set any nesting rules. The bottom of the bloq configuration page is where you create your atoms for the bloq. Creating atoms is exactly like creating columns in a Grid field.
Once you have created a few bloqs, it is time to create your Bloqs custom field and assign bloqs to it. Suppose we have a very simple "Pages" Channel in ExpressionEngine which contains 1 Bloqs field:
At the bottom of this Edit Field form is a list of all the bloqs you have defined. From here you select which bloqs will be made available to content editors when editing an entry in a channel that the Bloqs field is assigned to. Since bloqs can belong to one or more custom fields, you need to select which bloqs are available on a per-field basis.
Once you have created your bloqs, assigned them to a custom field, and assigned that field to a channel you can edit an entry and start building robust and dynamic pages in ExpressionEngine.
Once you have your field, bloqs, and atoms defined, you will want to learn how to render them to the page. Learn about [Template Tags](/bloqs/docs/template-tags) next.
## Entry Manager Support
Bloqs includes basic support for the new Entry Manager in ExpressionEngine 6, but the Bloqs custom field, and atoms inside a bloq must be set to searchable. All HTML tags will be removed from the content for display in the Entry Manager column.
# Hidden Config Options
### Collapse bloqs when dragging
By default, when you are dragging and reordering bloqs on an entry page, if the bloq is expanded, then it will remain expanded when dragging it. To collapse all bloqs when dragging, add the following value to your config.php file. Note that this can cause a slight jump in the page scrolling, which is why this is disabled by default.
```
$config['bloqs_collapse_on_drag'] = true;
```
### Collapse Children
When enabled child blocks are hidden and only revealed when the parent is expanded. Disabled by default.
```
$config['bloqs_collapse_children'] = true;
```
### Disable Logging
If you want to reduce the noise in your log you can turn it off. This is not recommended by default or while your site is in development because it can reveal some important information.
```
$config['bloqs_disable_logging'] = true;
```
### Field Caching
You can optionally cache the output of a Bloqs field. [Read more about it](/bloqs/docs/features/caching#field-caching).
```
$config['bloqs_cache_enabled'] = true;
```
### Confirm removal
By default Bloqs will immediately remove a bloq from an entry when the trash/delete icon is clicked. Enabling this option will present a confirmation modal to confirm the deletion.
```
$config['bloqs_confirm_bloq_removal'] = true;
```
### Strict tree structure
By default Bloqs will only warn you when the nesting structure of a bloqs field is incorrect and will still let you save the entry. When this is enabled the warning turns into an issue with more visual indicators that the user needs to correct something, and also will not let you save the entry the entry until the nesting structure is correct. This option is really only necessary if you have nesting enabled on a field, and you have nesting rules defined for your bloqs.
```
$config['bloqs_enable_strict_tree_structure'] = true;
```
### Usage Reports
In the control panel where you manage the bloq definitions there is a Usage column, which indicates in which entries the bloq is used in. On a large site this may add a little bit of load time to this page due to the query that is executed to find the usages across all fields and entries. Displaying the Usage column is default behavior. You can disable this column and the queries by using the config option.
```
$config['bloqs_disable_usage_reports'] = true;
```
### Bloq Field Assignments
Beginning in Bloqs 4.4.0, when a bloq is assigned to a field, and is used in a saved entry, you can not remove the bloq's assignment from that field. Removing the assignment will cause the bloq to disappear from existing entries (this has always been the behavior). **To prevent data loss**, and to make it more clear how bloqs are being used, the checkboxes are now disabled by default if the bloq is used in an existing entry. Below is a screenshot of what it may look like. The "*Used in X entries*" informs you how many entries the bloq is being used in for the current field. You can click the link to view the entries the bloq is assigned to. If the bloq is assigned to multiple fields, then the usage report when you click the link may report a different value than what you see on this screen. That is because the usage report is cumulative across all fields.
{% hint style="warning" %}
Note that this config option is not officially supported because it alters the intended default behavior of Bloqs and can cause data loss. If you experience visual or functional issues with this option disabled you can submit a support ticket, but there are no guarantees it will be addressed.
{% endhint %}
To prevent disabling of these checkboxes and return to the pre-4.4.0 behavior, add the following value to your config.php file.
```
$config['bloqs_disable_strict_assignment'] = true;
```
# Creating Bloqs
When creating a bloq you are required to add at least 1 atom (field) to the bloq. Atom names and short names can be reused. For example every bloq you create could have an atom with the Name of "Heading", and Short Name of "heading". However, you can't repeat short names in the same bloq. This behavior mimics that of a Grid field.
If you give an atom the short name of `__hidden` then it will not be displayed in the user interface when editing a bloq in an entry. An atom of this name has no other purpose than to fulfill the requirement that every bloq must contain at least 1 atom. Why would you need to do this you might ask? Glad you asked. This can be helpful if you need to create a bloq that has no configuration options or content values, but you might want to render something in a template when that bloq is added to an entry. This can be especially helpful if you're using the nested bloqs and want to give a group of bloqs a parent container to assist with layout rendering. For example:
```html
{bloqs_field}
{section}
{heading}
{bloqs:children}
{/section}
{container}
{bloqs:children}
{/container}
{content}
{heading}
{body}
{/content}
{/bloqs_field}
```
In that scenario you might have 3 bloqs in your entry nested like this:
> section
>
> container
>
> content
>
> content
>
> container
>
> content
# Template Tags
{% hint style="info" %}
Bloqs supports the Template Generator feature of ExpressionEngine 7.5. It'll output all the necessary tags for your Bloqs field. You will of course need to add your html around the tags, but the generated template will give you a jump start.
{% endhint %}
At the most basic level, templating with Bloqs is nothing more than the standard EE tag pair/tag process. But tag pairs in Bloqs go a bit deeper than what you might normally expect to encounter in ExpressionEngine. Let's take a look at an example so you can see how the logic plays out.
Lets say we have a single bloq type defined with 2 atoms:
* **Bloq Name:** Content Bloq
* **Bloq Short Name:** `{content_bloq}`
* **Bloq Atom Definitions:**
* **Atom Name:** Heading
* **Atom Short Name:** `{heading}`
* **Atom Name:** Body Content
* **Atom Short Name:** `{body_content}`
And this bloq type is added to a Bloqs custom field assigned to the Pages channel.
* **Field Type:** Bloqs
* **Field Name:** My Bloqs Field
* **Field Short Name:** `{my_bloqs_field}`
* **Selected Bloq Types:** Content Bloq
Given our base definitions, to output the content in a Pages Channel Entry, your template code would look similar to the following:
```html
{exp:channel:entries channel="page"}
{my_bloqs_field}
{/media_bloq}
{/my_bloqs_field}
{/exp:channel:entries}
```
{% hint style="info" %}
Note the file fields in the above example are prefixed with the bloq name. If you have *any custom field that uses a tag pair inside of a bloq* (e.g. File, Relationship, Ansel, or Simple Grid & Tables), you will likely have to prefix the field name with the bloq name. This is simply an issue with the native EE template parser.
```html
{my_bloq}
{my_bloq:my_ansel_field}
{/my_bloq:my_ansel_field}
{/my_bloq}
```
You may also want to avoid prefixing your bloqs with the same name as the bloqs field, and atom's with the same name as the parent blog's field name. Prefixing is handy in most cases, but the ExpressionEngine template parser can get confused. If you run into any template parsing issues, this should be the first thing you look into.
```html
{exp:channel:entries channel="page"}
{bloqs_field}
{bloqs_field_hero}
{hero_heading}
{hero_content}
{/bloqs_field_hero}
{/bloqs_field}
{/exp:channel:entries}
```
{% endhint %}
A slight more advanced example including a *Feature Component* bloq:
```html
{exp:channel:entries channel="page"}
{my_bloqs_field}
{content_bloq}
{heading}
{body_content}
{/content_bloq}
{feature_component}
{if bloqs:is:first_child}
{/if}
{feature_name}
{bloqs:children}
{if bloqs:is:last_child}
{/if}
{/feature_component}
{/my_bloqs_field}
{/exp:channel:entries}
```
At the bottom of a Bloqs custom field settings page will be a live basic example template based on the bloqs you've created for your project you can use to get started. Once you've created your basic field tag pairs, you may need to use Context Variables to assist in the rendering of the output. Read more about [Context Variables](/bloqs/docs/context-variables) next.
If you are using the bloq nesting feature, then [more template examples are available](/bloqs/docs/features/nesting#template-tags).
# Twig/Blade
The following is a basic example of how to render a Bloqs field with nested bloqs using Twig. If you're using Blade, the concepts are identical, just slightly different syntax for Blade.
Note the include statements are passing an array of possible template names to include in the brackets. If the first template file is not found, it will skip it and attempt to render the next one. For example, if you have a bloq named "summary" and you want that bloq to render entirely different HTML, just create a template named `_bloq_summary.html` All other bloqs will render in the `_bloq.html` template. These template names are completely arbitrary and you can choose any names you want. In this example I have a `coilpack.group` folder with the `_bloq.html.twig` and `_atom.html.twig` templates inside.
```twig
{# entry.html.twig #}
{% for entry in exp.channel.entries.parameters(
{'channel': 'pages', 'entry_id': '4'}
) %}
{{ entry.title }}
{% for bloq in entry.bloqs %}
{% include [
('ee::coilpack._bloq_' ~ bloq.getDefinition().getShortName()),
'ee::coilpack._bloq'
] with {
'bloq': bloq
} %}
{% endfor %}
{% else %}
No blog entries
{% endfor %}
```
```twig
{# _bloq.html.twig #}
{% set bloqName = bloq.getDefinition().getShortName() %}
{% set isComponent = bloq.getDefinition().isComponent() %}
{% for atom in bloq.getAtoms() %}
{% include [
('ee::coilpack._atom_' ~ atom.getDefinition().getShortName()),
'ee::coilpack._atom'
] with {
'atom': atom
} %}
{% endfor %}
{% for child in bloq.getChildren() %}
{% include [
('ee::coilpack._bloq_' ~ child.getDefinition().getShortName()),
'ee::coilpack._bloq'
] with {
'bloq': child
} %}
{% endfor %}
```
```twig
{# _atom.html.twig #}
{# If your atom contains HTML, use the raw modifier, e.g. {{ atom | raw }} #}
{{ atom }}
```
If in this scenario there was an atom with the short name of `content_with_image`, and a template file named `_atom_content_with_image.html.twig` existed, it would be loaded instead of the `_atom.html.twig` template.
Twig is extremly flexible and there are probably a number of ways to approach building out a Bloqs field. This is a basic example of how to use an include to render a deeply nested Bloqs field.
Once you have a bloq variable you can access it's atoms and atom values directly via the dot notation:
```twig
{% for entry in exp.channel.entries.parameters(
{'channel': 'pages', 'entry_id': '4'}
) %}
{{ entry.title }}
{% for bloq in entry.bloqs %}
{{ bloq.heading }}
{{ bloq.summary }}
{% endfor %}
{% endfor %}
```
### Relationships
Accessing relationship field data in Twig or Blade is the same as accessing any other array.
```twig
{% for entry in exp.channel.entries.parameters(
{'channel': 'pages', 'entry_id': '4'}
) %}
{{ entry.title }}
{% for bloq in entry.bloqs %}
{% for relationship in bloq.relationship_field %}
{{ relationship.title %}
{% endfor %}
{% endfor %}
{% endfor %}
```
# Examples
### Creating a tabbed content group
Creating a tabbed content group in Bloqs is pretty easy when using nested bloqs. You can put as many bloqs or components inside of a tab. In this example there is a single component in each tab.
The template markup is where the magic happens. Since Bloqs lets you repeat the same tag pair more than once in the page, you'll create two different loops. The first loop is to render all of your tabs, either in a list, or in this example a series of buttons. And the second loop will render the actual tab panel itself, which will render the contents, or children of each tab, through the `{bloqs:children}` variable.
```
{block_tab}
{if bloqs:is:first_child}
{/if}
{/block_tab}
```
### Displaying Assets fields in Bloqs
```
{bloqs_field}
{asset_field}
{!-- Looping over multiple files in an Assets field --}
{asset_field:file}
{/asset_field:file}
{!-- Displaying a single file in an Assets field --}
{asset_field}
{/asset_field}
{/asset_field}
{/bloqs_field}
```
# GraphQL
Below is an example of querying Bloqs field data using GraphQL.
```graphql
query GetBloqsEntry {
exp_channel_entries(entry_id: "123", limit: 1) {
data {
entry_id
title
url_title
bloqs {
... on Bloqs__bloqs__basic_content {
_id
_block_name
_depth
_order
_parent_id
heading
content
note
}
... on Bloqs__bloqs__ansel_test {
_id
_block_name
_depth
ansel {
id
url
thumbnail_url
title
width
height
}
}
... on Bloqs__bloqs__media {
_id
_block_name
_depth
}
... on Bloqs__bloqs__related_content {
_id
_block_name
related_entries {
entry_id
title
url_title
}
}
... on Bloqs__bloqs__section {
_id
_block_name
_depth
}
... on Bloqs__bloqs__video {
_id
_block_name
reel
}
... on Bloqs__bloqs__single_relationship {
_id
_block_name
related {
entry_id
title
}
}
}
}
}
}
```
# Context Variables
All Bloqs fields have context variables available. Regardless of what your field or atom names are, the following special variables can be used in your Bloqs field tag pairs. These variables are **only available inside of a bloq tag pair** (the same level as an atom). For example:
```
{exp:channel:entries channel="page"}
{my_bloq_field}
{content_bloq}
{heading}
{bloqs:count}
{/content_bloq}
{featured_article_bloq}
{bloqs:count}
{/featured_article_bloq}
{bloqs:count}
{/my_bloq_field}
{/exp:channel:entries}
```
{% hint style="info" %}
Please note that as of version 4.4.0, there was a universal change in the Bloqs UI, documenation, and variables of all references of "block" and "blocks" to "bloq" and "bloqs". If upgrading from a version prior to 4.4.0, your old`{blocks:total_blocks}` variables will still work. For every variable listed below, there is an `{blocks:*}` alias for it. If you are using a version prior to 4.4.0, then you must use the old variable prefixes, e.g. `{blocks:*}`
{% endhint %}
`{bloqs:all_vars}`\
List out all of the variables below, and their values in your template for debugging purposes.
`{bloqs:id}`\
The unique ID of the current bloq being displayed.
`{bloqs:shortname}`\
The short name of the current bloq being displayed.
`{bloqs:template:shortname}`\
If the current bloq is a template wrapper, this will display the template's short name from it's definition data (`{bloqs:shortname}` will always be `__template_wrapper` , this variable helps provide a unique name to reference)
`{bloqs:count}`\
The count of the current bloq being displayed. The first bloq will have a value of "1", the next "2", etc.
`{bloqs:index}`\
The zero-based index of the bloq being displayed. The first bloq will have a value of "0", the next "1", etc.
`{bloqs:total_bloqs}`\
The total number of bloqs to display.
`{bloqs:total_rows}`\
The same as `{blocks:total_bloqs}` but for people who feel more comfortable with Grid terminology
`{bloqs:count:of:type}`\
The count of the current bloq being displayed for this particular type. The first bloq of this type will have a value of "1", the next "2", etc.
`{bloqs:index:of:type}`\
The zero-based index of the bloq being displayed for this particular type. The first bloq of this type will have a value of "0", the next "1", etc.
`{bloqs:total_bloqs:of:type}`\
The total number of bloqs of the current type to display.
`{bloqs:total_rows:of:type}`\
The same as `{bloqs:total_bloqs:of:type}` but for people who feel more comfortable with Grid terminology
`{bloqs:previous:shortname}`\
The shortname of the bloq that precedes the current bloq, or "" if this is the first bloq.
`{bloqs:next:shortname}`\
The shortname of the bloq that follows the current bloq, or "" if this is the last bloq.
`{bloqs:switch="one|two|three"}`\
Works the same way as the {switch=""} variable in a channel:entries tag, but with bloqs. Note that this takes into account *all* bloqs of the same type within a specific field. If using nested bloqs or components the context/depth of a bloq will not reset the switch value.
#### The following context variables are useful when using a nested bloqs field.
`{bloqs:is:first_child}`\
Boolean - If this bloq is the first child of a parent bloq.
`{bloqs:is:last_child}`\
Boolean - If this bloq is the last child of a parent bloq.
`{bloqs:root:id}`\
If a bloq is a child of another bloq, this will be the value of the nearest parent bloq at the root level.
`{bloqs:is:root}`\
Boolean - If this bloq is at the root level (it doesn't have any parents).
`{bloqs:parent:id}`\
The id of the parent bloq
`{bloqs:parent:ids}`\
Similar to `{bloqs:parent:id}`, but when the bloq is a child of another bloq, this will report all of it's parent bloq IDs up to the root level. For example: '123|124|125'
`{bloqs:parent:shortname}`\
The short\_name of the parent bloq
`{bloqs:children}`\
This will render all child bloqs of a current bloq. You do not need to do anything special when using this tag. Bloqs will automatically grab the content of other `{my_bloq}{/my_bloq}` tag pairs and insert them into their proper location.
`{bloqs:child:my_bloq}`\
**New in Bloqs 5.0** - Instead of using the :children tag, you can selectively choose which children of a bloq get rendered, and where in the parent bloq tag pair they get rendered. Note, however, that if your template markup does not include a child tag of a particular bloq, but the bloq exists in the Entry data, it will not render on the front-end. These child tags and the `{bloqs:children}` tag are mutually exclusive.
`{bloqs:children:total_bloqs}`\
If a bloq has children, display how many children it has.
`{bloqs:children:total_rows}`\
The same as `{bloqs:children:total_bloqs}` but for people who feel more comfortable with Grid terminology
`{bloqs:siblings:total_bloqs}`\
How many siblings, at the same nesting level, the current bloq has.
`{bloqs:siblings:total_rows}`\
The same as `{bloqs:siblings:total_bloqs}` but for people who feel more comfortable with Grid terminology
`{bloqs:depth}`\
**New in Bloqs 5.0** -Use this variable to output an integer value of how deep the current bloq is inside of a nested bloq structure.
`{bloqs:count:at:depth}`\
**New in Bloqs 5.0** -Just like the {count} variable, this will output an integer value of the total bloqs at the same depth as the current bloq. If you have a single root level bloq with 3 children, the first child will have a {bloqs:count:at:depth} value of 1, and the last will have a value of 3, but the {bloqs:count} value of the 3rd child will be 4, since it is the 4th total bloq displayed.
#### Variable Modifiers
`:total_bloqs`\
`{your_field_name:total_bloqs}` returns the number of total bloqs that the field contains. This may be useful for conditionally including the field. E.g., `{if "{your_field_name:total_bloqs}" > "0"}`.
`:total_bloqs` - with "type" parameter (optional)\
`{your_field_name:total_bloqs type="shortname"}` will return the number of bloqs defined for a particular type, as specified by the bloq type shortname.
### Bloq Variables
Bloq variables are an advanced feature. If you add a parameter to your Bloqs field tag pair with the prefix `bloq_var_`, then the value of that parameter will be made available within your bloq tag pairs. This parameter can override, or workin tandem with the `bloq_var`'s when [nesting bloqs](/bloqs/docs/features/nesting).
{% hint style="info" %}
As of version 4.9, `{bloq_var_[name]}` and `{bloqs:get:[name]}` are interchangable.
{% endhint %}
```
{exp:channel:entries channel="page"}
{my_bloq_field bloq_var_some_key="some-value"}
{content_bloq}
{heading}
{body_content}
{if bloq_var_some_key == "some-value"}
Do something
{/if}
{/content_bloq}
{/my_bloq_field}
{/exp:channel:entries}
```
### Bloq Variable Setters & Getters
As of version 4.9, Bloqs now has variable setters and getters, which are very similar to ExpressionEngine's [Layout Variables](https://docs.expressionengine.com/latest/templates/layouts.html#layout-variables). So similar infact that it uses the same parsing code. For example you can set a variable with a value and later reference the variable in a child bloq, or the next bloq in the sequence if not using the nesting feature.
```
{exp:channel:entries channel="page"}
{my_bloq_field}
{section_wrapper_bloq}
{bloqs:set name="foo" value="bar"}
{/section_wrapper_bloq}
{content_bloq}
{bloqs:get:foo}
{/content_bloq}
{/my_bloq_field}
{/exp:channel:entries}
```
#### Bloq Variable Scoping
You can also set a variable in a child bloq, and pass a value back up to it's immediate parent bloq. Scoping currently only supports bloq IDs as values. Text based named scoping is not currently supported.
```
{exp:channel:entries channel="page"}
{my_bloq_field}
{section_wrapper_bloq}
{bloqs:get:scoped:foo}
{/section_wrapper_bloq}
{content_bloq}
{bloqs:set name="foo" value="bar" scope="{bloqs:parent:id}"}
{/content_bloq}
{/my_bloq_field}
{/exp:channel:entries}
```
If you're not using the nesting feature, and rendering bloqs sequentially, you can send a variable value to a previous bloq.
```
{exp:channel:entries channel="page"}
{my_bloq_field}
{section_wrapper_bloq}
{bloqs:get:scoped:foo}
{/section_wrapper_bloq}
{content_bloq}
{bloqs:set name="foo" value="bar" scope="{bloqs:previous:id}"}
{/content_bloq}
{/my_bloq_field}
{/exp:channel:entries}
```
Finally, you can also set a variable and reference it from *all* of it's parent bloqs (note the variable modifier is `:ids`, not `:id`).
```
{exp:channel:entries channel="page"}
{my_bloq_field}
{section_wrapper_bloq}
{bloqs:get:scoped:foo}
{/section_wrapper_bloq}
{row_wrapper_bloq}
{bloqs:get:scoped:foo}
{/row_wrapper_bloq}
{content_bloq}
{bloqs:set name="foo" value="bar" scope="{bloqs:parent:ids}"}
{/content_bloq}
{/my_bloq_field}
{/exp:channel:entries}
```
# Add-on Developers
Working on some custom functionality, or building out a new fieldtype? Bloqs was built with you in mind and comes packaged with some features to make your life as easy as possible.
### Adding Fieldtype Support
Getting your field type working with Bloqs is a 3 step process, all of which are pretty straight forward.
#### **Step 1 - Your Field Type must be compatible with Grid**
You’re going to start out the process by first getting your field type to be compatible with Grid. If you haven’t done this before, EllisLab has put together some excellent documentation to help you out with the process which you can find here:
Once your field type is compatible with Grid, you're just about there!
#### **Step 1.b - Depending on the complexity of your fieldtype**
If your fieldtype creates new HTML elements, similar to adding new rows in a table, and stores the new row HTML template in a `
