Power Shortcodes are very useful in two cases:
They allow using power features that are not normally available for security reasons.
When you use a pattern repeated very often, with potentially only minor differences. You can use Power Shortcodes as a template.
Powers Shortcodes allow you to define custom Dynamic Shortcodes easily by composing other Shortcodes.
Note: When writing Power Shortcodes keep in mind that they can be written only by administrators but then also used by contributors.
How do they work
A Power Shortcode has two components: a name and its content. You can insert this in the WordPress dashboard (more below). A Power Shortcode can then be used everywhere else with {power:name}, where name is the name you defined before.
Suppose we have a Power Shortcode with name "welcome-user" and code
{if: {call:is_user_logged_in}
"You are not logged in!" [Welcome {user:name}!]
}
Then you can use it anywhere with the Power Shortcode passing it the name as an argument: {power:welcome-user}.
It will work as if you had written the Power Shortcode code directly.
How to create and edit Power Shortcodes
Go to the plugin's Settings and the Power Shortcodes page. The interface contains a list of the Power Shortcodes defined, a button to add a new one, and a button to save the shortcodes to the database.
The name is an identifier that should contain no spaces and only characters, digits, underscores, and minus signs (for example my-shortcode). In the content you can insert any text mixed with shortcodes definitions, as you normally would elsewhere.
Passing arguments to Power Shortcodes (advanced)
You can pass arguments and key arguments to Power Shortcodes as you would with normal shortcodes. In the content, you can fetch them with the args and keyargs shortcodes.
args returns an array of the positional arguments passed while keyargs returns an array of the key arguments passed. You can use the accessor filters (||) to fetch the arguments.
For example
Name of the Power Shortcode: welcome
Code of the welcome Power: {if: {eq: {keyargs:||lang} it} Benvenuto Welcome} {args:||0}!
Usage: {power:welcome Joe}
Result: Welcome Joe!
Usage: {power:welcome Giovanni @lang=it}
Result: Benvenuto Giovanni!
Power Shortcodes are not escaped
Since they can be written only by administrators, the content of the Power Shortcodes itself is not escaped. This means that you can use it to create reusable JS templates:
This is using the {user:login} shortcode to create an alert that says hello user! Just put {power:greet-alert} inside any page.
Notice that other Dynamic Shortcodes inside Power Shortcodes are automatically escaped unless you use them with the raw! keyarg.
Shortcodes whose export value is not a string
By default, a Power Shortcode is rendered as a string.
Use the keyarg value! to interpret it as a value.
So, for example, if the code of the power test is:
{array: a b c}
and you use it with
{pw:test}
you only get the string "Array" as a result, and you can't, for instance, use {pw:test||1} to get "b".
However, {pw:test @value! || 1} would correctly output "b".