/administrate-wp-weblink-plugin

Primary LanguagePHPGNU General Public License v2.0GPL-2.0

Deprecated: This WordPress Plugin is No Longer Supported

⚠️ Important Notice: This WordPress plugin is no longer actively supported or maintained.

Administrate Weblink2 Shortcodes Plugin

Requires at least: 5.0.0

Tested up to: 5.3.2

Stable tag: 1.0.0

License: GPLv2 or later

License URI: http://www.gnu.org/licenses/gpl-2.0.html

Description

Administrate Wordpress Plugin to facilitate the usage of weblink 2 widgets. The plugin exposes weblink 2 functionality into WordPress short-codes, also it creates a Gutenberg block to customize / inject short-codes in the posts content.

Installation

The plugin is not released on wordpress.org yet, so if you need to use it please contact Administrate by sending us en email at support@getadministrate.com and we will send you the files needed to install the plugin.

or

Clone the plugin to your project Administrate Weblink2 Shortcodes Plugin

Note: you can add it to the main WordPress project as a git sub-module.

Steps:

  1. Upload the zip files "admwswp.zip" to the /wp-content/plugins/ directory
  2. Activate the plugin through the 'Plugins' menu in WordPress
  3. Head over the settings page: /wp-admin/admin.php?page=adminstrate_shortcodes
  4. On the General Config tab use the Weblink portal domain. [YOUR_APP_NAME].administrateweblink.com or it could be a Vanity Domain that Administrate Team has setup for you.
  5. Set the Time zone to the one you operate in and you should be good to go after hitting the save button.
  6. The remaining configuration tabs will affect the default attributes offered by the Gutenberg block short-code builder as default params.

Settings page

Dependencies

The plugin depends on the following plugins:

  • ACF PRO this plugin is used to generate the settings page.
  • ACF Timezone Field this plugin is used to set a timezone filed used in the settings page.

*Note: There might be an effort in the future to remove the above dependencies.

Gutenberg block

The plugin generates a custom Gutenberg block that can be used form the UI to generate and inject the different Weblink embedded widgets using the following short-code variations based on selected widget type [administrate-widget] The custom Gutenberg block is somehow similar to the Weblink Builder App but it injects a WordPress short-code in the Post/Page content and this short-code gets converted to an Embedded Weblink Widget by the plugin added all the necessary libraries and field mapping.

Gutenberg block select

Gutenberg block ui

Shortcodes

[administrate-widget]

This short-code handles all Weblink widget types based on the provided type some of the attributes will not be used.

Cart
  • type = "Cart"
  • hide_edit_button defaults to false if set to true will hide the edit cart button.
Basket
  • type = "Basket"
  • cart_url defaults to '' Set this to the URL of the page showing the Cart widget.
  • show_basket_popover defaults to false if set to true the Basket widget will display a mini cart popover.
PathDetails
  • type = "PathDetails"
  • path_id this to be set to the Learning Path TMS ID.
TrainingRequest
  • type = "TrainingRequest"
  • interest_id this to be set to the Course/Learning Path TMS ID.
PathObjectives
  • type = "PathObjectives"
  • path_id this to be set to the Learning Path TMS ID.
  • show_cart_buttons defaults to true if set to false hide the car buttons and enables the onObjectiveSelection for further customization.
  • show_remaining_places_filter defaults to false if set to true show the remaining places filter.
  • minimum_places_remaining defaults to null
  • locations defaults to '' Set this to the TMS location ID you need to filter the results by location.
  • location_filter defaults to false if set to true show the locations filter.
CourseDetails | Catalogue | Category | EventList
  • type = "CourseDetails|Catalogue|Category|EventList"
  • category_id defaults to '' set this to the TMS category ID to filter results.
  • course_code defaults to '' set this to the TMS Course ID to filter results.
  • location_name defaults to '' set this to the TMS Location Name to filter results.
  • locations defaults to '' Set this to the TMS location ID(s) separated by comma , you need to filter the results by a set of locations.
  • to_date defaults to '' Set this to end date needed to filter on Y-m-d\TH:i:s.u\Z
  • from_date defaults to '' Set this to start date needed to filter on Y-m-d\TH:i:s.u\Z
  • catalogue_type defaults to All this field is used to set the Courses type to show allowed values: course|path
  • date_filter defaults to false if set to true show the date filter.
  • course_filter defaults to false if set to true show the courses filter.
  • category_filter defaults to false if set to true show the category filter.
  • event_list_order defaults to '' this field is used to contact multiple sorting like: locationName-asc,start-asc if set it will override event_list_order_field
  • event_list_order_field defaults to title field system name to sort on allowed values: title|locationName|start|classroomStart|lmsStart
  • event_list_order_direction defaults to asc sorting direction allowed values: asc|desc
  • event_title defaults to false if set to true show the title column.
  • event_location defaults to false if set to true show the location name column.
  • event_venue defaults to false if set to true show the venue name column.
  • event_start_date defaults to false if set to true show the start date column.
  • event_duration defaults to false if set to true show the duration column.
  • event_time defaults to false if set to true show the time column.
  • event_places_remainingdefaults to false if set to true show the places remaining column.
  • event_price defaults to false if set to true show the price column.
  • event_addtocart defaults to true if set to false hide the add to cart button column.
  • classroom_start_date defaults to false if set to true show the local column.
  • classroom_duration defaults to false if set to true show the local column.
  • classroom_time defaults to false if set to true show the local column.
  • lms_start_date defaults to false if set to true show the local column.
  • lms_duration defaults to false if set to true show the local column.
  • lms_time defaults to false if set to true show the local column.
  • pager_type defaults to loadMore this field is used to set the pager type allowed values: loadMore|Full
  • show_time_zone defaults to true if set to false hide the timeZone.
  • show_locale defaults to false if set to true show the local column.
  • more_filter defaults to false if set to true activate the additional filters from_time_of_day|to_time_of_day|days_of_week.
  • from_time_of_day defaults to null Set this to start time of day needed to filter on H:i
  • to_time_of_day defaults to null Set this to end time of day needed to filter on H:i
  • days_of_week defaults to null Set this if you needed to filter on the days of week separated by comma , for a lost of days allowed values: Mon|Tue|Wed|Thu|Fri|Sat|Sun
Applicable to all Above types
  • id defaults to '' if left empty the plugin will auto generate a widget ID. Example: weblink_PathObjectives_1655300627_desktop
  • screen_size defaults to desktop this is used to apply a suffix to the auto generated ID

[admwswp-addToCart]

  • path_id The TMS LP ID to add to the cart
  • course_id The TMS COURSE ID to add to the cart
  • class defaults to "btn btn-lg btn-primary"

This Short-code Adds a button on the page to trigger adding a Course or LP to Weblink cart / Basket (This short-code will be deprecated in the future and replaced by Weblink embedded widget [administrate-widget type='addToCart' course_id='COURSE_ID'])

[admwswp-eventRequest]

  • button_text The TMS LP ID to add to the cart
  • tms_id The TMS COURSE ID to add to the cart
  • wrapper_id defaults to "btn btn-lg btn-primary"
  • popup_title defaults to "btn btn-lg btn-primary"
  • popup_class defaults to "btn btn-lg btn-primary"
  • class defaults to "btn btn-lg btn-primary"

This Short-code Adds a button on the page to trigger a popup with a event Request Weblink widget.

Developers Section

Setup

The project includes a Dockerized setup for WordPress which can be started by running the following command from the project root:

docker-compose up -d

You can then go to http://localhost:8888 to set up your WordPress site.

By default, we are pointing at production for things like Portal Auth, this can be changed in admwswp.php where we define ADMWSWP_WEBLINK_ENV.

Once your WordPress site is set up, you will need to install and activate the Plugin Dependencies. Once these are activated, you can activate this Plugin (Administrate Weblink2 Shortcodes).

Custom Filters

Assets Management

admwswp_weblink_css

  • Defined: $webLinkCss = apply_filters('admwswp_weblink_css', $webLinkCss);
  • Usage: add_filter('admwswp_weblink_css', '[THEME_CUSTOM_METHOD]', 10, 1);
  • instructions: This filter is available in case we need to override the default weblink CSS file URL to me loaded on the frontend.

admwswp_weblink_js

  • Defined: $webLinkJs = apply_filters('admwswp_weblink_js', $webLinkJs);
  • Usage: add_filter('admwswp_weblink_js', '[THEME_CUSTOM_METHOD]', 10, 1);
  • instructions: This filter is available in case we need to override the default weblink JS file URL to me loaded on the frontend.

admwswp_weblink_js_ver

  • Defined: $webLinkJsVersion = apply_filters('admwswp_weblink_js_ver', $version);
  • Usage: add_filter('admwswp_weblink_js_ver', '[THEME_CUSTOM_METHOD]', 10, 1);
  • instructions: This filter is available in case we need to override the default weblink JS version string, this could be used to inherit the active theme version and act as browser cache buster after deploying and updating the theme version.

Configuration Params

admwswp_weblink_args

  • Defined: $weblinkMountArgs = apply_filters('admwswp_weblink_args', $weblinkMountArgs);
  • Usage: add_filter('admwswp_weblink_args', '[THEME_CUSTOM_METHOD]', 10, 1);
  • instructions: This filter is available in case we need to add a hook to apply some changes to the Weblink mount args before generating the JS mount method and injecting it into the webpage to trigger the rendering of a particular weblink widget.

admwswp_weblink_config

  • Defined: $webLinkConfig = apply_filters('admwswp_weblink_config', $webLinkConfig);
  • Usage: add_filter('admwswp_weblink_config', '[THEME_CUSTOM_METHOD]', 10, 1);
  • instructions: This filter is available to enable the developers to override some default configuration params used to initialize the Weblink on the website.
  • Params:
  • cartUrl defaults to '' can be used to pass custom Cart page URL
  • timezone defaults to the time zone set on the plugin config page can be used to override the timezone value
  • locale defaults to '' if left blank weblink will resolve the browser locale else it can be used to override the locale value and force a specific language to webslink widgets loaded on the web page
  • localeStrings defaults to [] empty array this can be used to pass on some localization overrides for specific language code keys to value mapping strings. this param will take a multidimensional array as follow array('nl' => array("addToCart"=>"Add to Cart"), 'fr' => array("addToCart"=>"Ajouter au panier"))
  • hooks defaults to array('onCheckoutNavigation' => '',) it exposes a custom hook to enable the dev to do some extra logic or action once the user triggers the checkout button on the cart widget. Some use cases are to alter the checkout URL adding params to it, check if a user is logged in to wordpress or any 3rd party SSO before going to checkout.

Settings Defined Variables

The plugin has some global settings defined in the main plugin file admwswp.php those can be overridden in wp-config.php if needed

// This defined constant is used to override weblink config 
// to using Administrate `staging` portals to authorize and execute graphQl queries 
if (! defined('ADMWSWP_WEBLINK_ENV')) {
    define('ADMWSWP_WEBLINK_ENV', 'prod'); // prod or staging
}

Tech

This plugin skeleton and file structure is generated using the WordPress plugin boilerplate generator.

Changelog

1.6.4
  • Fix parsing widget configurations with single quotes by replacing them with the corresponding ASCII codes to prevent the shortcode being cut-off early by Wordpress. Fix parsing widget configurations with & replacing them with & to work around a bug in WPTexturize.
1.6.3
  • Fix parsing widget configurations with arrays by replacing [] characters with their corresponding ASCII codes to prevent the shortcode being escaped early by Wordpress.
1.6.2
  • Add product_route which allows catalogue cards to automatically link to https://{YOUR_WEBSITE}/{THIS_ROUTE}/product-name-with-dashes instead of using embedded navigation
  • Add configuration which overrides all other configuration options on the shortcode. This can be used to copy and paste a WebLink Widget configuration from WebLink Builder and use it in WordPress
1.6.1
  • Add timeout before triggering add to cart weblink popup.
1.6.0
  • Add the ability to disable all e-commerce aspect on the site and only serve course with event request form. (Disable Cart, Basket, Checkout, adding to cart etc...)
  • Add event Request Popup Short-code
  • Add show language flag to Gutenberg block builder
  • Add showTimezone attribute to event listing short-code builder
  • Add Location and ShowLocationFilter to PathObjectives
1.5.0
  • Add time interval before loading weblink widgets until main JS loads and weblink is made available for consumption.
  • Add cartUrl custom param to weblink config mapping.
  • Fix Typo in Widget type dropdown.
  • Add pager to weblink widget wrapper plugin.
  • Add Sanitization for filter params.
  • Add ability to setup weblink to connect to staging or prod.
  • Add ability to hide edit button on cart widget.
1.4.0
  • Add support for multiple location IDs on eventList short-code.
  • Ability to override the checkout button action with custom hooks onCheckoutNavigation.
1.3.0
  • Update field mapping for path.
  • Change Attribute names.
1.2.0
  • Add cart_url and screen_size attributes to compact cart short-code.
  • Add GiftVoucherBalance Short-code.
  • Add course ID mapping for Events list.
1.1.0
  • Wrap widget setup inside panel and make catalogue type a select list.
  • Fix field mapping in short-code.
  • Fix plugin name in defined constants.
  • Add check on plugin activation for ACF-pro and ACF-timezone.
  • Add weblink missing styles main.css.
1.0.0
  • Setting page to enter weblink credentials and default parameters.
  • Short-code builder as Gutenberg block.