Inline Shortcodes

The first type is an 'inline' shortcode. This is a simple shortcode that does not require an end tag. Just reference the shortcode and provide a list of parameters and you’re done!

{[ youtube id:'8kpHK4YIwY4' showinfo:'false' controls:'false' ]}

Block Shortcodes

The second type of shortcode is the 'block' type. Like other Lava commands it has both a start and an end tag. The content you provide inside the tags will be passed to the shortcode for use in its template.

{[ parallax image:'http://cdn.wonderfulengineering.com/wp-content/uploads/2014/09/star-wars-wallpaper-4.jpg' speed:'0.2' height:'400px' position:'top' contentpadding:'20px' ]}
<h1>Hello World</h1>
{[ endparallax ]}

Select the Proper Shortcode Type

As we already mentioned it's very important that you select the proper type of shortcode before you start using it. Changing it in the future means having to update all of your Lava templates that use it. The biggest factor in your decision of which type to use will be how much data your shortcode will pass and if any of the data has repeating sections. Let's consider a couple examples.

The parallax shortcode needs to access a large amount of HTML to place inside the parallax section. While this could be passed through a standard parameter {[ parallax content:'... this would be limiting in a number of ways. For example, the content could not have any line breaks and it would not be allowed to have any single quotes.

Consider next the googlemap place holder. It allows you to enter a variable number of map points. Again, you could use a single inline parameter, but this would be very difficult for the person who wanted to use your shortcode.

Finally, think about the youtube shortcode. In this example only a small amount of configuration is required, so an inline shortcode works great.

It comes down to how much data is being passed by the shortcode. For larger amounts of data, use the block shortcode type. For lesser amounts, use inline.

Configuring Parameters

You can configure parameters when setting up your shortcodes. While you technically don't need to configure parameters, any parameter that another person adds to the shortcode will be passed to your Lava template. Configuring the parameters when you write your shortcode provides two advantages.

1. Configuring the parameter guarantees that it will exist when it's passed to your Lava. This means you don't have to check for its existence. Instead, if you need to check if the parameter has a value, you can do a simple check to see if it's empty.
2. Configuring a parameter allows you to provide a default value. Again, this simplifies your Lava and reduces the number of lines of code you'll need to write.

The Lava you develop for your shortcode is passed in all of the parameters found on the shortcode tag as well as any parameters you defined as the author. Rock also provides an additional parameter 'uniqueid' which is a unique identifier for you to use for things like CSS id's and variables in your Javascript. It takes the form of 'id-4535a4a9-1b82-4d5b-9120-8c9c41eefcd6'. You don't need to use this identifier, it's just provided as a convenience to you.

Enabled Lava Commands

You can enable certain Lava commands to be able to run within your shortcode. These commands do not need to be configured in the source block to run. For instance, if your shortcode is being used on a web page and requires the RockEntity command, the HTML Block does not need to have the command enabled if you've configured access on your shortcode.

Adding Lava Shortcodes in Rock

Lava Shortcodes can be found at Admin Tools > CMS Configuration > Lava Shortcodes.

Pictured above, you can assign categories to your shortcodes. This lets you group shortcodes according to their function, and allows you to filter the list of shortcodes by category. A single shortcode can be assigned to multiple categories. The categories for a shortcode can be added from the Lava Shortcode Detail page, pictured below.

We want to ensure the shortcode list is searchable in this manual. For this reason, we've listed below the shortcodes that are pictured above.

Click Show Details for any of the shortcodes to view its summary, code and parameters. To add a new shortcode, press the + button. This will take you to the Lava Shortcode Detail screen.

This screen is where you designate which type of shortcode you're creating, which parameters to use, the actual Lava markup code, and any Lava commandsyou want enabled. Remember, it's always a good idea to supply a description for the benefit of other users. Click Save when you're done. Super easy!

Block Content

The content (everything between the start and end tags) that the user adds to your shortcode is accessible to your template using the {{ blockContent }} variable. For instance, the parallax shortcode would use this variable to place the content inside the parallax section of a page.

Lava will be run across the markup of the {{ blockContent }}. You can disable this behavior by adding a parameter to your shortcode with the key of disablelavamerge and a value of 'true'.

Block Configuration

The block configuration can also be placed in the block contents using the syntax:
[[ itemname parameter:'value' parmeter2:'value' ]] content [[ enditemname]]
When Rock is parsing your shortcode, these options will be parsed and removed from the {{ blockContent }}. They will then be provided to your template as variables. How these variables are created is super powerful and will help reduce the amount of Lava that is created. Let's dig deeper to see how this works by looking at some examples.

As you've probably seen, the syntax of the googlemap shortcode is:

{[ googlemap height:'400px' scrollwheel:'false' draggable:'false' ]}
    [[ marker location:'33.640705,-112.280198' title:'Spark Global Headquarters']]
        <strong>Spark Global Headquarters</strong><p>
        It's not as grand as it sounds.<br>
        <img src='https://rockrms.blob.core.windows.net/misc/spark-logo.png' width="179" height="47" />
    [[ endmarker ]]
    [[ marker location:'33.52764, -112.262571']][[ endmarker ]]
{[ endgooglemap ]}

After parsing, your template would have access to the 'height, scrollwheel, draggable' variables just like any shortcode. It would also be provided an array of 'markers' using the variable name 'markers'. (Yes, we know... clever...) Each 'marker' in the 'markers' array would have a variable for 'location, title, ...' It would also have a variable called 'content' which would contain the text within the start and end configuration tags (in this case, the HTML for the Google Maps Info Window).