Packages

  2. Home
  4. Docs
  6. Packages
  8. WordPress Core Package

WordPress Core Package

WordPress Core Package enables you to utilize core WordPress features, like accessing post based data, accessing custom database tables and to use various WordPress functions.

Functions

These are the functions you can use in Expression Language when you enable the WordPress Core Package.

Content Retrieval:

Meta Data:

Options Management:

User and Authentication:

Content Manipulation:

Post Management:

Email and Communication:

URLs and Site Information:

Hooks:

Miscellaneous:

  • is_wp_error($thing): Checks if a given variable is a WordPress error.
  • wp_call_user_func($callback, $args): This is a wrapper for the call_user_func() function, with the specificity that arguments are passed as an indexed array, instead of being spread. It also has the ability to include the required WordPress includes to make the function available (if they are not available by default).

Components

Init Current Auth User Element

Initiates the authentication process of a WordPress User and displays the data of the user.

When to use?

Use this component when you want to link WordPress User Accounts with an Alexa Skill.

How to use:

  1. Ensure that you have configured and propagated your service to Amazon Alexa with Account Linking enabled in the Account Linking Mode set to ‘Installation’.
  2. In the Name field, enter a variable name for the user to store the loaded user object in the context.
  3. Leave the Set as Current User checked to set the current WordPress user as the User that has linked the account. Initially, no user is set in the service. Functions which leverage wp_get_current_user() will benefit the most from this option being enabled, which will be used in the service.
  4. To prompt account linking directly from the element, check Prompt for linking. You can also use the Prompt Account Linking element, which is in the convo-core package, to initiate prompt account linking.
  5. After the account linking process is successfully finished, you can access the WP_User object using the following examples:

    • ${user.ID}
    • ${user.nickname}
    • ${user.user_email}
    • ${user.get().get('user_email')}
    • ${user.get().to_array()['user_email']}
    • ${user.get().has_cap('manage_convoworks')}

For more information on the WP_User object, please refer to the Official WordPress documentation here.

WP Mail Element

When to Use

The WP Mail Element is used to send emails using the wp_mail() function in WordPress. If the sender’s email address is not specified in the element, the email address of the WordPress admin will be used. Multiple email addresses can be used, separated by a comma.

How to Use

The WP Mail Element supports various email address formats, including:

  • user@example.com
  • user@example.com, anotheruser@example.com
  • User <user@example.com>
  • User <user@example.com>, Another User <anotheruser@example.com>

For more information about the wp_mail() function, please visit the WordPress Developer Reference.

WP DB Element

Allows you to manipulate the WP database by inserting, deleting, selecting, etc.

When to Use

Use whenever you need data from the database that could not reasonably be obtained through WP Queries, or perhaps if you have an advanced idea for which you need the database.

How to Use:

  1. First, choose an Action from the dropdown list.

    • You might notice that Select and Query both give you a custom field into which to enter a query. What’s the difference?
    • Select uses get_results(), while Query uses the generic query() method.
  2. If you chose Insert, Update, Delete, or Replace, you will need to fill out key -> value pairs that correspond to the columns in the table you’re modifying.
  3. In addition, you will be able to enter a format string. To do this, for each value, enter the corresponding format you wish to use.
  4. Enter a name and pick a scope type under which to store the last_result. This is the result from the last query you’ve run. Make sure to store it with e.g. Set Parameter Element if you wish to keep it later on, because subsequent queries will overwrite this result.
  5. If you are inserting data into the database, enter a name and pick a scope type for the insert_id that is automatically generated when you insert. As stated before, if you need this data, make sure to store it so it doesn’t get overwritten.

WP Insert Post Element

Inserts or updates a WordPress post.

When to Use

Use the WP Insert Post Element when you want to insert a post in WordPress from your Skill.

How to Use

  1. Enter a Name for your recently created post.
  2. Type false in Fire After Hooks if you don’t want to fire the after insert hooks.
  3. Fill out WP Post args which are described here, except tax_input and meta_input. The following params: meta_input and meta_input are handled in WP Post tax input and WP Post meta input
  4. If you want to update a post, add the ID to WP Post args. More info is available here
  5. If you want to add tax_input, fill out WP Post tax input. More info on that is here.
  6. If you want to add meta_input, fill out WP Post meta input.

After the element is executed, you will get either a WP_Post or WP_Error object as a result of wp_insert_post( array $postarr, bool $wp_error = false, bool $fire_after_hooks = true ).

On Success

Elements in On Success will be executed if the post was inserted successfully.

You will get the recently created WP_Post in the form of (${status.post}) object and be able to access its properties like this:

  • ${status.post.ID}
  • ${status.post.post_title}
  • ${status.post.post_content}
  • etc.

On Failure

Elements in On Failure will be executed if the post was not inserted successfully.

You will get the WP_Error in the form of (${status.wp_error}) object and be able to access its properties like this:

  • ${status.wp_error.errors}
  • ${status.wp_error.error_data}
  • etc.

WP Insert User Element

Inserts a WordPress user.

When to use?

Use this element when you want to insert a user in your WordPress site from an account linking option other than ‘installation’.

How to use:

  1. Enter a Name for your recently created user.
  2. Retrieve the user name from the Init Amazon User Element like ${user.name}.
  3. Retrieve the email from the Init Amazon User Element like ${user.email}.
  4. If you want to use a different role than what is associated with your WP Installation, check the property Use Custom Role and enter a role in the Role property.
  5. Or just select a role from the available WP Roles.
  6. If you want to add user_meta_input, fill out the WP User Meta Input field.

After the element is executed, you will get either a WP_User or WP_Error object as the result of wp_insert_user( array|object|WP_User $userdata ).

On Success or On User Exists

Elements in On Success will be executed if the user was inserted successfully.

Elements in On User Exists will be executed if the user already exists.

You will get the recently created WP_User in the form of (${status.user}) object and be able to access its properties like this:

  • ${status.user.ID}
  • ${status.user.data.user_login}
  • ${status.user.data.user_email}
  • etc.

On Failure

Elements in On Failure will be executed if the user was not inserted successfully.

You will get the WP_Error in the form of (${status.wpError}) object and be able to access its properties like this:

  • ${status.wpError.errors}
  • ${status.wpError.error_data}
  • etc.

WP Loop Element

Allows looping over WP Query Context single page results inside the element.

When to use?

You can use this element when you have a limited number of results and do not require pagination.

If you need full-featured pagination, please use WP Loop Page and WP Loop Post blocks.

WP Loop Page Block

WP Loop Page Block enables the pagination of WP_Query results in a convenient and straightforward manner. It comes with built-in pagination and post selection mechanisms.

When to use

Use WP Loop Page Block when you want to display a list of posts, products, or any other custom post type in a paginated manner.

How to use

To use WP Loop Page Block, drag and drop the block onto your WordPress page or post. Then, select the WP_Query to loop through, the number of items per page, and any additional parameters. You can customize the pagination labels and styling to match your site’s design.

Examples

  • Displaying a paginated list of blog posts on the homepage.
  • Creating a paginated product catalog page.
  • Displaying a list of events in chronological order with pagination.

WP Loop Post Block

Use this component to access a selected loop post with built-in navigation features. Similar to the WP Loop Page Block, it offers automatic navigation capabilities, but for posts instead of pages.

When to Use

Use this component when you need to navigate through posts and access specific loop posts.

How to Use

Simply drag and drop the WP Loop Post Block onto your canvas and configure the settings to your liking. This component comes with built-in post navigation (Next, Previous) intents that will automatically trigger the desired operation on the WP Query Context.

Examples

Here are some examples of how to use the WP Loop Post Block:

  • To display a single post, select the post ID in the component settings.
  • To display multiple posts, select a category or tag in the component settings.
  • Use the built-in post navigation intents to navigate through posts.

WP Media Context

Defines WP_Query which will return audio files to be streamed via audio player components.

When to use

This component is used to define the WP_Query that will return audio files to be streamed via audio player components.

How to use

All arguments are passed to the real WP_Query class except offset which is 0 and paged which is always set to true, meaning that there is no pagination. Setting the posts_per_page you will set the max results in a playlist (20 by default).

You can use expressions when defining arguments. Check how to use expressions on the Convoworks documentation pages. The expressions are evaluated in the service scope, so you cannot use internal variables that are available inside container elements (e.g. Loop element).

Other parameters

All other parameters are optional and are allowed to be empty by the platforms (e.g. artwork), or the Convoworks provides required values. All parameters accept expressions that will be evaluated in the service context. Most of them are also in the post context, meaning that the “post” variable is available in the context (the real \Wp_Post object from the loop).

Default settings parameters

Default loop status and Default shuffle status define initial values that will be used when your user starts the player for the first time.

Media info

WP Media Context provides media info data that you can use through connected components (e.g. Media info element, Media block). In these components, you will provide a name under which this data (associative array) will be available, and here are the fields it consists of.

  • current IAudioFile, current song
  • next IAudioFile, next song if exists
  • count integer, playlist songs count
  • last boolean, is the current song the last
  • first boolean, is the current song the first
  • song_no integer, current song, starting from 1
  • loop_status boolean, is the loop mode enabled
  • shuffle_status boolean, is the shuffle enabled
  • playing boolean, is the player currently playing

Mp3File (Song Descriptor Class)

These examples on how to access the various pieces of information apply to the current and next variables from the Media Info.

  • getFileUrl() access to the file URL from current or next field in the media info
  • getSongTitle() access to the song title from current or next field in the media info
  • getArtist() access to the artist from current or next field in the media info
  • getSongImageUrl() access to the image URL from current or next field in the media info
  • getSongBackgroundUrl() access to background image URL from current or next field in the media info

WP Post Context Component

Use this component to query items from the wp_posts table and convert their values into a catalog source for Amazon.

When to Use

Use this component when you have post values that you want to convert into an entity source. For example, if you have a custom post type that you want to use as an entity.

How to Use

  1. Enter the Entity name you wish to “override” with the catalog values. Make sure to create a dummy entity with the same name in the entity editor beforehand. You do not have to add any values to it since it will be replaced with the catalog.
  2. Filter the posts you want by adding Query parameters. For instance, if you want to get all the posts of a given type, you can use post_type: <your_post_type_here> and post_status: any.
  3. Final value is what you will turn each post into. After the posts have been queried and found, each post will be iterated over, and you need to provide an expression that will turn each post into a SINGLE STRING VALUE. You can use WP functions such as get_the_title(), get_the_meta(), and so on.

WP Query Context

This component defines WP_Query to be used as the source for other WP specific components and maintains the pagination and post selection info across the session.

When to use

Use this component when you want to use WP_Query as a source for other WP specific components and maintain pagination and post selection info across the session.

How to use

All arguments are passed to the real WP_Query class except offset which is calculated dynamically and paged which is always set to true.
You can use expressions when defining arguments. To learn more about expressions, check out the
Convoworks documentation.
The expressions are evaluated in the service scope, so you cannot use internal variables available inside container elements like the Loop element.

Maintaining the pagination

This component keeps track of the current page during navigation through results. If you want to rewind it to the beginning, for example if the sort order changes, provide an expression that evaluates to true to the Rewind navigation component property. If you want to maintain pagination yourself, set the offset parameter in args.

Page and post info

WP Query Context provides page info and post info data that you can use through connected components. In this component, you provide a name under which this data (associative array) is available, and here are the fields it consists of:

Page info fields

  • last (boolean) – indicates if the current page is the last page
  • first (boolean) – indicates if the current page is the first page
  • page_no (integer) – indicates the current page, starting from 1
  • query (actual WP_Query object) – provides the actual WP_Query object

Post info fields

  • abs_last (boolean) – indicates if the current post is the last post in the results
  • abs_first (boolean) – indicates if the current post is the first post in the results
  • abs_post_no (integer) – indicates the position of the post in all results, starting from 1
  • last (boolean) – indicates if the current post is the last post on the current page
  • first (boolean) – indicates if the current post is the first post on the current page
  • post_no (integer) – indicates the position of the post on the current page, starting from 1
  • post (actual WP_Post object) – provides the actual WP_Post object
  • meta (loaded meta for the current post) – an associative array in the key-value manner

WP Query Element

Gives access to the page info (and WP_Query object) defined by the WP Query Context component.

When to Use?

Use this element to quickly check if there are any results from the WP_Query object and prepare the appropriate user workflow accordingly. For example, you may define different responses or conversation steps based on whether there are no results, only one result, or multiple pages of results.

Not in the WordPress Loop

While you have access to the WP_Query object and its members, you cannot use WordPress functions without arguments as you are not in the WordPress loop. However, you can loop over the query.posts array.

If you want to do a quick, fully functional loop over resulting posts, use the “WP Loop Element” and place it inside the “Has Results” flow.

WP Table Context

This component allows you to write a custom select query to retrieve values from the WP database and convert each item into a value for an Amazon catalog.

When to use?

You can use this component if you have specific values in the WP database that you want to use as catalog values. For example, you may want to query a quiz table to retrieve all the quiz names.

How to use?

  1. Enter the name of the entity you wish to “override” with the catalog values under the Entity name field. Create a dummy entity with the same name in the entity editor beforehand. You do not have to add any values to it since it will be replaced with the catalog.
  2. Under the Query field, enter a SELECT query. Note that you can use public fields and methods from the global wpdb object, such as wpdb.prefix.
  3. In the Final value field, provide an expression that will turn each row of the query into a SINGLE STRING VALUE. After the query has been executed and rows are found, each row will be iterated over, and you can access every row under the row name. For example, if you want to access the ID of each row, you can use row.ID.

WP Update User Meta Element

Updates metadata of a WP User.

When to use?

Use this element when you want to update metadata of a user in your WordPress site.

How to use:

  1. Enter a Name for your recently updated user status variable.
  2. Retrieve the User ID from the Init current auth user Element like ${user.ID}, or use any other method of your choice.
  3. Fill out the metadata of the user you want to update in the WP User meta input.

After the element is executed, you’ll either get a WP_User object or a false boolean value as the result of get_user_by($field, $value).

On Success

Elements in the On Success section will be executed if the user was found and some metadata were provided.

You’ll get the recently updated WP_User object in the form of (${status.user}), and you’ll be able to access its properties like this:

  • ${status.user.ID}
  • ${status.user.data.user_login}
  • ${status.user.data.user_email}
  • etc.

On Failure

Elements in the On Failure section will be executed if the user was not found.

You’ll get an error message in the form of (${status.error}) object.

Exception

An exception will occur if no metadata was provided.