> For the complete documentation index, see [llms.txt](https://wplake.gitbook.io/advanced-views/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wplake.gitbook.io/advanced-views/post-selections/embedding-shortcode.md).

# Selection embedding shortcode

In Advanced Views, [Post Selection](/advanced-views/getting-started/first-post-selection.md) embedding happens using native WordPress shortcodes. Each *Post Selection* has its own unique shortcode that can be pasted into any location, regardless of the theme, editor, or page builder you're using. 

Shortcodes also support arguments, allowing you to customize the behavior of the same entity in different contexts.

## 1. Shortcode format

Each *Post Selection* shortcode should contain at least 2 arguments:

```bbcode
[avf-post-selection name="Name" id="651d5d75bfdf2"]
```

1. `name` argument - used for clarification purposes only and doesn't play any functional role. 
2. `id` argument - associates the shortcode with a specific *Layout*.

## 2. Optional arguments

The following shortcode arguments can be added to any *Post Selection* shortcode:

### 2.1) class - adding HTML class

This argument allows you to add a class to your *Post Selection* main wrapper dynamically. 

In most cases, you should add all the classes directly to your *Post Selection,* but in some cases you will need to assign this class dynamically.

{% code overflow="wrap" %}

```shortcode
[avf-post-selection name="Name of Selection" id="651d5d75bfdf2" class="YOUR_CLASS_HERE"]
```

{% endcode %}

### 2.2) user-with-role - restricting visibility by role

Both "user-with-roles" and "user-without-roles" arguments allow you to restrict access to the specific *Post Selection*. 

{% code overflow="wrap" %}

```shortcode
[avf-post-selection name="Name of Selection" id="651d5d75bfdf2" 
user-with-roles="ROLE1,ROLE2" user-without-roles="ROLE1,ROLE2"]
```

{% endcode %}

{% hint style="info" %}
"**Restrict**" means that the shortcode won't be rendered, so if you'd like to show a restriction type message to users, then consider customizing the *Layout* template to check user roles there*.*
{% endhint %}

### 2.3) custom-arguments - transiting fields

Using this argument, you can pass any custom arguments to the [*Post Selection* Controller](/advanced-views/post-selections/code-fields/selection-controller.md):

{% code overflow="wrap" %}

```shortcode
[avf-post-selection name="Name of Selection" id="651d5d75bfdf2" custom-arguments="name=value,another-name=another-value"]
```

{% endcode %}

{% hint style="warning" %}
Custom arguments are available only inside the *Layout* Controller. They're not available directly in the *Layout* template. If you need to use them inside the template, you can transit them in the snippet.   
{% endhint %}

## 3. Displaying inside theme templates

To embed *Post Selection* into theme templates, you can either render the text shortcode using a native [WordPress do\_shortcode function](https://developer.wordpress.org/reference/functions/do_shortcode/), or employ the Advanced Views API: 

{% code overflow="wrap" %}

```php
<?php

// a) using WordPress do_shortcode
echo do_shortcode('[avf-post-selection name="Name of Selection" id="651d5d75bfdf2"]');

// b) using the special plugin class
use Org\Wplake\Advanced_Views\Bridge\Advanced_Views;

echo Advanced_Views::post_selection_shortcode('651d5d75bfdf2', 'name')
// adds HTML class to the main wrapper
 // ->set_class('YOUR_CLASS_HERE')
 // restricts access by roles
 // ->set_user_with_roles(['administrator'])
 // ->set_user_without_roles(['suspended'])
 // you can pass custom arguments, including objects, arrays, etc.  
//->set_custom_arguments([
    //    'name' => 'value',
       // 'another-name' => ['my array'],
   // ])
    ->render();
```

{% endcode %}