Shortcodes and Widget
Note: There are addtional shortcodes and widgets in the AreteX shopping cart plugin.
AreteX™ makes extensive use of WordPress shortcodes to connect your eCommerce services to your web site's front end.
; ?>)
Many (but not all) AreteX™ shortcodes can be automatically generated by selecting your desired options with the AreteX™ editor button (located on WordPress editor pages). The AreteX™ editor button appears on most major WordPress content creation screens, including Pages, Posts and many custom post types.
Details about exactly which shortcodes can be automatically generated can be found under each shortcode category tab.
Product Presentation - These are shortcodes that help you display information about your products on your pages, as well as create purchase buttons.
Payee Registration - This shortcode allows you to set up a front end registation form for your contributors and referrers.
Coupons & Tracking - Has information about the AreteX™ Coupon Widget as well as shortcodes to allow you to accept coupons on your site and display information about them.
The [aretex_product_info] Shortcode
The shortcode: aretex_product_info allows you to show basic information about the product on your WordPress page.
Automatic Generation
This shortcode can be automatically generated with the AreteX™ editor button on the WordPress Page/Post editor.
; ?>)
Click for full size image.
; ?>)
Usage Details
The shortcode: aretex_product_info has the format:
[aretex_product_info code='CODE']Information About the Product.[/aretex_product_info]
The code attribute is required. It is the product code you wish to present information about.
The aretex_product_info shortcode supports the following substitution fields:
:code: :name: :description: :itemnote: :regular_price:
When you use the shortcode generator, it will look something like this.
; ?>)
Each substitution field is replaced by the appropriate product data value when the shortcode is rendered onto your WordPress page. The following illustration shows how the fields in the AreteX™ Product (Catalog & Products / Products (Add or Edit) map to the shortcode substitution values. Click on the image for a full size view.
; ?>)
; ?>)
Editing And Displaying
You can use the WordPress editor to add your own text and formatting to the aretex_product_info
shortcode so you can present the product as you see fit.
; ?>)
; ?>)
The [aretex_buynow] Shortcode
The [aretex_buynow] shortcode will generate a "buy now" button for most of the products in your AreteX™ database.
Please Note:Do not use the [aretex_buynow] shortcode for Paid Memberships. Select the Membership tab for information about Paid Membership purchase buttons.
The code generated "behind the scenes" with this shortcode will take into account relevant information, such as the pricing model any offer code and/or paid referrer, as well as fundamental information (such as the WordPress username and email address) required for basic deliverable authorizations like paid content.
When the user selects the generated "Buy Now" button, they will be automatically directed to your PCI compliant payment form on the AreteX™ server to complete their purchase.
Automatic Generation
This shortcode can be automatically generated with the AreteX™ editor button on the WordPress Page/Post editor.
To automatically generate and paste a "Buy Now" button onto your WordPress page: From your WordPress admin screen, Add or Edit your page or post, then select the AreteX™ Editor button. On the AreteX™ Shortcode Generator popup select the Product Presentation tab, find and select your product, select the Buy Button box, and then Generate & Paste Shortcode.
Usage Details
The shortcode: aretex_buynow has the format:
[aretex_buynow code='CODE']button or image html[/aretex_buynow]
The code attiribute is mandatory. It is the product code you are generating the buy button for.
You may put one button or img tag inside the aretex_buynow shortcode,
with whatever styling information you need to make it attractive on your site. As illustrated in the following image:
; ?>)
; ?>)
Click for full size image. Image of Button Generated by Sample
; ?>)
Image of Button Generated by Sample
; ?>)
Click for full size image.
; ?>)
The [aretex_paid_content] Shortcode
With the aretex_paid_content shortcode, you may charge for nearly any type of content you create on your WordPress site. Only those users who have paid for it will be able to see it.
Although this is a very flexible shortcode with a lot of options, in its simplest form all you have to do is wrap the shortcode around the content you wish to charge for:
; ?>)
This shortcode is used to display different content to your users depending on their authorization status for this deliverable. Note: Authorization Status in regards to Paid Content refers to a customer's right to access the deliverable.
Although it is not strictly necessary for the customer to have a user account on your WordPress site to purchase paid content, they must be logged onto your site to view paid content. If the customer purchases paid content without being logged on, when they do register and login, the email address they provide on the payment form is matched to their WordPress email address to authenticate proper authorizaton to content.
The exact authorization status of a given deliverable is determined for a specific user based on 1) the options you chose when you set up the deliverable, 2) the current payment status, and 3) when the payment was made.
Automatic Generation
There are two ways to automatically generate aretex_paid_content shortcodes: 1) the Setup Wizard in AreteX™ and 2) the AreteX™ Editor button on the WordPress Page/Post editor.
The Paid Content Setup Wizard
; ?>)
Click for full size image.
; ?>)
The New Paid Content Wizard will automatically create a new Product, a new Paid-Content Deliverable, and generate the most approriate shortcodes for the options you have selected - including the purchase button.
On the last step of the wizard, you have two choices with the generated shortcodes: 1) Copy and paste them into a text file for later or 2) Paste them into your WordPress page during your current browser session.
Important Note: 1) Session storage is temporary. When you close your browser window, the shortcodes will be lost. 2) Only the latest wizard generated shortcodes are saved in the browser session.
If you do not plan on using the shortcodes right away, you may want to copy and paste them to a text file on your computer.
To use the shortcodes immediately:
1) Add or Edit a new WordPress Page, Post or custom post type, where you want the paid content to go.
2) Select the AreteX™ Editor Button on the WordPress editor.
3) If there are shortcodes stored in session, you will have the option to paste them onto your content immediatley.
Note: Once you have pasted the shortcodes onto your Page or Post, be sure to add content your customers are paying for.
; ?>)
Click for full size image.
; ?>)
The AreteX™ Editor Button on the WordPress Page/Post Editor
To automatically generate aretex_paid_content shortcodes and paste them into your Pages and Posts, first, navigate to the Page or Post editor on your WordPress admin screen. Next, select the Paid Content tab. Select the paid content deliverable code and the various status conditions you want to address within your conent. Then, generate and paste the shortcodes. For a dicussion on valid status condtions and the distinction between deliverable codes and products, see the next section.
; ?>)
Click for full size image.
; ?>)
Usage Details
The [aretex_paid_content] shortcode is of the following format:
Important Note: Use "text mode" on the page editor when copying and pasting shortcodes to be sure all embedded HTML is rendered properly.
Both the deliverable_code and status attributes are required.
Paid content is considered by AreteX™ to be a deliverable. As explained in Catalog & Products / Delivery Specifications a deliverable can be part of any number of products via the product's manifest. This allows you the flexiblity to bundle your content as you see fit. The deliverable_code lets AreteX™ know which content deliverable you are putting on your Page or Post.
Generally speaking, a user is considered Authroized if they have a timely payment for any product with this deliverable in its manifest.
The content within the shortcode an be any valid WordPress content, including other shortcodes. That means you can embed audio, video, file download links, chatroom entrances or any other content you can put in WordPress.
The status attribute determines the conditions under which the content within the shortcode is displayed. A full list of valid status condtions are listed below.
Valid status Values
| Status | Explanation | Show/Hide |
|---|---|---|
| Authorized | User is authorized to view content. If no status is specified, this status is the default. | |
| [aretex_paid_content deliverable_code="$deliverable_code" status="Authorized"] ---- YOUR PAID CONTENT GOES HERE ---- [/aretex_paid_content] | ||
| !Authorized | User is NOT authorized to view content. The exclamation mark (!) means "NOT". The reason the user is not authorized is irrelevant. | |
| [aretex_paid_content deliverable_code="$deliverable_code" status="!Authorized"] ---- YOUR 'You are not authorized' CONTENT GOES HERE ---- [/aretex_paid_content] | ||
| Expired | Only valid when you have a Duration specified. The content within the shortcode with this status will be displayed when the duration has passed and has not been renewed. | |
| [aretex_paid_content deliverable_code="$deliverable_code" status="Expired"] ---- YOUR 'Your access authorization has expired' CONTENT GOES HERE ---- [/aretex_paid_content] | ||
| !Expired | The authorization has NOT expired. The exclamation mark (!) means "NOT". | |
| [aretex_paid_content deliverable_code="$deliverable_code" status="!Expired"] ---- YOUR 'Your access authorization has not (yet?) expired' CONTENT GOES HERE ---- [/aretex_paid_content] | ||
| Pending | Only valid when you have an Availablity greater than 0. The content within the shortcode with this status will be displayed when the delivery is pending. | |
| [aretex_paid_content deliverable_code="$deliverable_code" status="Pending"] ---- YOUR 'Your access authorization is pending' CONTENT GOES HERE ---- [/aretex_paid_content] | ||
| !Pending | The content within the shortcode with this status will be displayed any time the content is not pending. The exclamation mark (!) means "NOT". | |
| [aretex_paid_content deliverable_code="$deliverable_code" status="!Pending"] ---- YOUR 'Your access authorization is not pending' CONTENT GOES HERE ---- [/aretex_paid_content] | ||
| Completed | Only valid when you have a Total Re-Auth specified. The content within the shortcode with this status will be displayed when the maximum number of deliveries has been completed. | |
| [aretex_paid_content deliverable_code="$deliverable_code" status="Completed"] ---- YOUR 'Your access authorization has been completed' CONTENT GOES HERE ---- [/aretex_paid_content] | ||
| !Completed | The content within the shortcode with this status will be displayed when the maximum number of deliveries has NOT been completed. The exclamation mark (!) means "NOT". | |
| [aretex_paid_content deliverable_code="$deliverable_code" status="!Completed"] ---- YOUR 'Your access authorization has not been completed' CONTENT GOES HERE ---- [/aretex_paid_content] | ||
| Authorized|Completed | (Advanced Useage) The "pipe" symbol (|) means OR. This content will be displayed if the user is Authorized OR the maximum number of deliveries has been completed. Note: ANY of the statuses above may be "OR"ed together. If ANY ONE status in an OR condition is valid, the content will be shown. | |
| [aretex_paid_content deliverable_code="$deliverable_code" status="Authorized|Completed"] ---- YOUR APPROPRIATE CONTENT GOES HERE ---- [/aretex_paid_content] | ||
| !Authorized&!Pending | (Advanced Useage) The "and" symbol (&) means AND. This content will be displayed if the user is NOT Authorized AND NOT Pending. Note: ANY of the statuses above may be "ANDED" together. If ALL statuses in an AND condition are valid, the content will be shown. | |
| [aretex_paid_content deliverable_code="$deliverable_code" status="!Authorized&!Pending"] ---- YOUR APPROPRIATE CONTENT GOES HERE ---- [/aretex_paid_content] | ||
| LoggedIn | The content within the shortcode with this status will be displayed when the user is logged in regardless of the user's authorization status for this deliverable. Note: The AND, OR operators (|, &) -- see above -- will NOT work with this status. | |
| [aretex_paid_content deliverable_code="$deliverable_code" status="LoggedIn"] ---- YOUR USER IS LOGGED IN CONTENT GOES HERE ---- [/aretex_paid_content] | ||
| !LoggedIn | The content within the shortcode with this status will be displayed when the user is NOT logged in. The exclamation mark (!) means "NOT". Note: The AND, OR operators (|, &) -- see above -- will NOT work with this status. | |
| [aretex_paid_content deliverable_code="$deliverable_code" status="!LoggedIn"] ---- YOUR USER IS NOT LOGGED IN CONTENT GOES HERE ---- [/aretex_paid_content] | ||
Paid Membership Purchase Shortcodes
There are three shortcodes related membership purchase. They are to be used instead of [aretex_buynow]:
[aretex_paid_registration] - This generates a simple front-end registration form for customers to sign up with.
[aretex_register_button] - This shortcode goes inside the aretex_paid_registration content and generates a "buy" button.
[aretex_role_button] - This shortcode generates a "buy" button for a membership upgrade.
You should use these shortcodes to sell any Product with a Membership deliverable in its Manifest. That is because behind the scenes, these shortcodes work with the WordPress registration system as well as the WordPress Roles and Capablities system.
Paid Membership purchase shortcodes have two purposes: 1) Registration and 2) "Upgrade" Payment. Registration allows non-members to sign up and pay for access to your site. The role they are assigned when payment is complete depends on the product and the membership deliverable in the associated manifest. Upgrade Payments allow existing members to purchase a new role. Note: It's a really good idea to only have one membership deliverable in any given manifest.
You may have other types of deliverables (i.e. paid content) in the product manifest when using Paid Membership purchase shortcodes. AreteX™ will handle delivery authorization of other deliverables appropriately when it is bundled with a membership purchase. (The converse is not true. Please do not use the aretex_buy_now shortcode for selling memberships.)
Automatic Generation
There are two ways to automatically generate paid membership shortcodes: 1) the Setup Wizard in AreteX™ and 2) the AreteX™ Editor button on the WordPress Page/Post editor.
The Paid Membership Setup Wizard
; ?>)
Click for full size image.
; ?>)
The New Paid Membership Wizard will automatically create a new Product, a new Paid Membership Deliverable, and generate the most approriate shortcodes for the options you have selected - including the purchase button.
On the last step of the wizard, you have two choices with the generated shortcodes: 1) Copy and paste them into a text file for later or 2) Paste them into your WordPress page during this browser session.
Important Note: 1) Session storage is temporary. When you close your browser window, the shortcodes will be lost. 2) Only the latest wizard generated shortcodes are saved in the browser session.
If you do not plan on using the shortcodes right away, you may want to copy and paste them to a text file on your computer.
To use the shortcodes immediately:
1) Add or Edit a new WordPress Page, Post or custom post type, where you want the membership purchase buttons to go.
2) Select the AreteX™ Editor Button on the WordPress editor.
3) If there are shortcodes stored in session, you will have the option to paste them onto your content immediately.
Note: Once you have pasted the shortcodes onto your Page or Post, be sure to update the button text.
; ?>)
Click for full size image.
; ?>)
The AreteX™ Editor Button on the WordPress Page/Post editor
To automatically generate Paid Membership purhcase shortcodes and paste them into your Pages and Posts, first, navigate to the Page or Post editor on your WordPress admin screen. Next, select the Paid Membership tab. Follow the prompts for the membership product you wish to sell.
; ?>)
Click for full size image.
; ?>)
Usage Details
Registration: - What follows is an illustration of how [aretex_paid_registration] and [aretex_register_button] work together.
; ?>)
Click for full size image.
; ?>)
The [aretex_paid_registration] shortcode generates the registration form. It needs to contain at least one [aretex_register_button] shortcode to function.
If [aretex_register_button] does not have a product_code attribute, it will be a free registration. Free registrations are processed through the normal WordPress registration system, and not AreteX™.
If [aretex_register_button] does have a product_code attribute, the customer who selects the generated button will be sent to your PCI compliant payment form on the AreteX™ server. AreteX™ will authorize the appropriate access upon completed payment. The temporary password will emailed to the customer by your WordPress system (not the AreteX™ Server). The temporary password will be the Transaction Id generated by the credit card processor. This process makes use of your WordPress WP-Cron to poll AreteX™ for pending registration authorizations.
You may put any content you wish into the [aretex_paid_registration] shortcode (including other shortcodes). It will appear after the registration form.
If [aretex_register_button] should contain only button or img tags, you may style as you wish. Note that this plugin uses ajax for registration setup, so any button tag should contain the type="button" attribute.
; ?>)
Click for full size image.
; ?>)
Role Upgrade - Use the [aretex_role_button] shortcode to generate a "buy" button for a membership upgrade.
The shortcode: aretex_role_button has the format:
[aretex_role_button product_code='CODE']button or image html[/aretex_buynow]
The product_code attiribute is mandatory. It is the product code you are generating the buy button for.
You may put one button or img tag inside the aretex_role_button shortcode,
with whatever styling information you need to make it attractive on your site. It is illustrated in the following image:
; ?>)
Note: It is a "best practice" to use your chosen membership management plugin to only display an upgrade option to members who 1) are not in the role or 2) have not upgraded past the role. (i.e don't show a "Silver Upgrade" to a "Gold" user.)
Payee Registration
Whether a payee is a Referrer, a Contributor or both they will need to be registered on your site to access their Payment Tracking and Reporting screen (PTR).
There are two ways to register payees: Back End and Front End. Regardless of which way they are assigned, they will be required to agree to both your terms of service and the AreteX™ terms of service before having full access to their PTR screen. (See WP Integration/ PTR Integration for more details.)
For Back End registration, see Reports & Management / Payees / Payee Management / Add. If your payee is already a member of your site, select their username in the Payee Managment screen when you Add or Edit their record.
The rest of this tab addresses Front End payee registration. Front End payee registration allows people who are currently not members of your web site to sign up from a page on your site.
The [aretex_payee_signup] Shortcode
The aretex_payee_signup cannot be automatically generated by any wizard or from the AreteX™ editor button on the WordPress Page/Post editor. When you put the shortcode [aretex_payee_signup] onto a WordPress Page or Post, it will generate a special registration form. When a potential payee signs up using this form, they are registered as a user on your site with the role AreteX Payee. WordPress will send them their temporary password as is usual. When they sign on to their user dashboard, the Payment Tracking and Reporting (PTR) menu option will be available to them. See WP Integration/ PTR Integration for information on the PTR screen.
If you put the [aretex_payee_signup] shortcode on your page without any modifications, it will generate the default sign up form.
You may modify the payee sign up form by adding attributes and content.
Attributes
The [aretex_payee_signup] shortcode supports the following attributes: captcha, commission_group and parent.
captchaThe captcha attribute has three options: None, visualCaptcha (Default) and visualCaptcha1 - These attribute values are case-sensative.
- None - No captcha is displayed.
- visualCaptcha (default) - This plugin uses a modified copy of Visual Captcha version: 4.2.0 to provide additonal security to discourage automated sign ups for payment. The user will be asked to drag and drop a specific image into the circle. See the image of the Default Payee Registration Form for an example.
- visualCaptcha1 This is an alternate arrangement of the visualCaptcha graphics.
The commission_group attribute is specifically for referrer registration. If the value of the commission_group
attribute is a valid commission group code (See Setup / Payouts / Commission Structures) the new payee will automatically be assigned to that commission group upon successful registration.
Example: [aretex_payee_signup commission_group='AFF1']
(This would assign the new registrant to the commission group with the code AFF1, if such a commission group exists in your AreteX™ database.)
The default value of commission_group is None.
The parent attribute is specifically for referrer registration when you have a commission_group with a multi-tier commission structure. The default value for this attribute is None.
The attribute determines which payee will get the 2nd tier commission when this new referrer makes a sale. (That payee is known as the "Upline" payee, or "parent")
If the attribute value is tracking, then the upline payee is determined by the referral tracking code. The person who referred the new registrant (either by URL or Coupon)
will receive the 2nd Tier commission.
Example: [aretex_payee_signup parent="tracking" commission_group='AFF1']
If the attribute value is a valid WordPress User Name that user will be the upline payee. Of course, this requires that the specified WordPress user also be registered as a payee.
The specified payee will always receive the 2nd Tier commission. The following example assumes you have a WordPress user with the username AffiliateManager.
Example: [aretex_payee_signup parent="AffiliateManager" commission_group='AFF1']
Content
You may customize the registration button by putting a single button or img tag within the shortcode content section. You may style the button as you need to match your site.
To add a customized button or button image use this format: [aretex_payee_signup]Your Image or Button HTML[/aretex_payee_signup]
See the image Adding a Custom Button for an example.
; ?>)
Click for full size image.
; ?>)
When Captcha attibute is visualCaptcha1
; ?>)
Adding a Custom Button
; ?>)
Coupons & Tracking
For more information on setting up Coupons and Tracking codes see Catalog & Products / Coupons & Tracking
Note: None of the coupon shortcodes are automatically generated by any wizard or editor button.
Receiving Tracking Codes
AreteX™ can receive a tracking code either in the URL or as a "Coupon Code". This section addresses receiving it as a Coupon Code. For more information about receiving it on the URL see WP Integration / PTR Integration
AreteX™ Coupon Widget
This plugin provides a WordPress Widget that you can place on your site to recieve a coupon code. Like all WordPress Widgets, you may install it by going to Appearance / Widgets on your WordPress admin screen, then dragging it to your desired location.
Most of the options are self-explanitory. The "Current Coupon Text" option may require some addtional explanation. After a customer enters a valid coupon code, the "Current Coupon Text" is displayed at the bottom of the widget.
The primary purpose of the "Current Coupon Text" is to provide the user with assurance that "something happened" when they entered a valid Coupon Code. It will be displayed whenever a valid tracking code is in use (even if the tracking code came in via the URL).
You are provided with the following substitution values. You may use any, all or none of them as you see fit:
- :tracking: - This echos back the actual code in use.
- :description: - This is the offer description (See Catalog & Products / Coupons & Tracking / Offer Codes).
- :referrer: - This is the name of the person who provided the tracking code.
; ?>)
The [aretex_coupon_info] Shortcode
The [aretex_coupon_info] shortcode cannot be automatically generated with any wizard or on the AreteX™ editor button.
This shortcode allows you to put information about the current coupon in use on any Page or Post you which. It has essentially the same functionality as The "Current Coupon Text" option in the coupon widget.
The shortcode is of the form:
[aretex_coupon_info] --- YOUR CONTENT ---[/aretex_coupon_info]
You are provided with the following substitution values. You may use any, all or none of them as you see fit:
- :tracking: - This echos back the actual code in use.
- :description: - This is the offer description (See Catalog & Products / Coupons & Tracking / Offer Codes).
- :referrer: - This is the name of the person who provided the tracking code.
You can see what any of these are for any given tracking code (or Splash Code) with the Tracking Code Validator (Catalog & Products / Coupons & Tracking / Full Tracking)
If there is no valid coupon code in use, by default the shortcode will not generate any text.
The [aretex_coupon_info] shortcode supports the following optional attributes.
- allow_invalid - This is false by default, you can override it by setting it to "true" (i.e.) [aretex_coupon_info allow_invalid="true"] - With this setting the shortcode will generate text, even if no valid coupon is in use.
- tracking - This is the tracking value you want to display if no valid tracking code is in use: (i.e.) [aretex_coupon_info tracking="You have no valid coupon"].
- description - This is displayed if there is no valid offer description - (i.e.) [aretex_coupon_info description="Thank you for visiting."]
- referrer - This is displayed if there is no referrer, whether it's because the coupon is invalid or there was no referrer in the tracking code - [aretex_coupon_info referrer="Our Store"]
Image of the Tracking Code Validator
; ?>){kind=tracking}
Click for full size image.
; ?>){kind=tracking}
Widget and Shortcode Example
; ?>)
Click for full size image.
; ?>)
The [aretex_coupon_box] Shortcode
In addition to the AreteX™ Coupon Widget, you may accept coupons on any page of your site using the [aretex_coupon_box] shortcode. The widget is not required when using the [aretex_coupon_box] shortcode.
The shortcode is of the form [aretex_coupon_box submit="Submit Coupon Code"]Your content[/aretex_coupon_box]
Any content you provide will be displayed above the coupon input box. The submit attribute is optional. It is the text that will appear inside the submit button. If you do not provide text, the button will say "Submit Coupon Code"
In order to help you style the coupon box for your site or theme, the following css classes are used.
- aretex_coupon_form_wrapper - The entire form is wrapped in a div with this class.
- aretex_coupon_submit - This is the css class of the submit button.
By default, these classes have no definition, but if you wish to stylize the coupon box, you should define them in your stylesheet.
; ?>)