Add "Widget Promotions" (#277)

Author: rami-elementor

src/.vuepress/public/assets/img/elementor-widget-promotion.png

@@ -23,7 +23,15 @@ module.exports = [
     children: [
       'widget-structure',
       'widget-data',
-      'widget-categories',
+      {
+        collapsable: false,
+        sidebarDepth: -1,
+        children: [
+          'widget-information',
+          'widget-promotions',
+          'widget-categories',
+        ]
+      },
       'widget-dependencies',
       'widget-controls',
       'widget-rendering',

src/.vuepress/sidebars/widgets.js

@@ -19,7 +19,9 @@ Learn more about widget anatomy and how to create your own:
 
 * [Widget Structure](./widget-structure/)
 * [Widget Data](./widget-data/)
-* [Widget Categories](./widget-categories/)
+  * [Widget Information](./widget-information/)
+  * [Widget Promotions](./widget-promotions/)
+  * [Widget Categories](./widget-categories/)
 * [Widget Dependencies](./widget-dependencies/)
 * [Widget Controls](./widget-controls/)
 * [Widget Rendering](./widget-rendering/)

src/widgets/index.md

@@ -2,7 +2,7 @@
 
 <Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Intermediate" />
 
-Every widget requires basic information such as the widget ID, label and icon.
+Every widget requires basic information such as the widget ID, label and icon. In addition, a widget can have optional data providing extra information like an external link describing how to use the widget or promotion to promote premium version of the widget.
 
 ## Data Methods
 
@@ -32,7 +32,7 @@ class Elementor_Test_Widget extends \Elementor\Widget_Base {
 	}
 
 	public function get_custom_help_url() {
-		return 'https://go.elementor.com/widget-name';
+		return 'https://example.com/widget-name';
 	}
 
 	protected function get_upsale_data() {
@@ -54,4 +54,4 @@ class Elementor_Test_Widget extends \Elementor\Widget_Base {
 
 * **Widget Help URL** – The `get_custom_help_url()` method is an optional method that sets a custom URL, where the user can get more information about the widget, below the controls.
 
-* **Widget Promotion** – The `get_upsale_data()` method is an optional method that is used to display promotions at the bottom of the widget panel.
+* **Widget Promotion** – The `get_upsale_data()` method is an optional method that is used to [display promotions](./widget-promotions/) at the bottom of the widget panel.

src/widgets/widget-data.md

@@ -0,0 +1,49 @@
+# Widget Information
+
+<Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Intermediate" />
+
+Elementor widget need to have a unique ID used in the code, and an addition basic information used in the Elementor editor.
+
+## Widget Name/ID
+
+To set a unique ID for the widget, use the `get_name()` method. This string is used in code and in the database. The name should include only lowercase letters and it should not contain spaces (use `_` instead).
+
+```php
+class Elementor_Test_Widget extends \Elementor\Widget_Base {
+
+	public function get_name() {
+		return 'widget_name';
+	}
+
+}
+```
+
+## Widget Title
+
+Widget title is the label used in the Elementor editor. The end user will see this text when interacting with different panels. The title should use internalization functions to make the string translatable to other languages.
+
+```php
+class Elementor_Test_Widget extends \Elementor\Widget_Base {
+
+	public function get_title() {
+		return esc_html__( 'My Widget Name', 'textdomain' );
+	}
+
+}
+```
+
+## Widget Icon
+
+Each widget has not only a label but also an icon. This icons is displayed in different location in the Editor, like the elements panel and the navigator panel. It's not a required field, but very recommended.
+
+Widgets can use any [Elementor icons](https://elementor.github.io/elementor-icons/) or [FontAwesome icons](https://fontawesome.com/), returning the icon CSS class. Custom icons can also be used.
+
+```php
+class Elementor_Test_Widget extends \Elementor\Widget_Base {
+
+	public function get_icon() {
+		return 'eicon-code';
+	}
+
+}
+```

src/widgets/widget-information.md

@@ -0,0 +1,53 @@
+# Widget Promotions
+
+<Badge type="tip" vertical="top" text="Elementor Core" /> <Badge type="warning" vertical="top" text="Intermediate" />
+
+<img :src="$withBase('/assets/img/elementor-widget-promotion.png')" alt="Elementor Widget Promotion" style="float: right; width: 300px; margin-left: 20px; margin-bottom: 20px;">
+
+Elementor widgets have two builtin location in the widget panel for promotions and upsells.
+
+The first option is a simple "Need Help?" url which is an external link with general information about the widget.
+
+The second option is a call-to-action area with offers to upgrade to premium widgets/products/services.
+
+## Widget Help URL
+
+Help links displayed at the bottom of the widget panel bellow all the sections. This is a builtin feature providing the user consistent user experience across all Elementor widgets.
+
+Each widget have the option to set an external link containing general information about that specific widget and instruction how to use it.
+
+```php
+class Elementor_Test_Widget extends \Elementor\Widget_Base {
+
+	public function get_custom_help_url() {
+		return 'https://example.com/widget-name';
+	}
+
+}
+```
+
+## Widget Promotion
+
+Promotions are a way for freemium plugins to offer upsells to upgrade to premium widgets/products/services. Widget promotions displayed at the bottom of the widget panel.
+
+```php
+class Elementor_Test_Widget extends \Elementor\Widget_Base {
+
+	protected function get_upsale_data() {
+		return [
+			'condition' => ! \Elementor\Utils::has_pro(),
+			'image' => esc_url( ELEMENTOR_ASSETS_URL . 'images/go-pro.svg' ),
+			'image_alt' => esc_attr__( 'Upgrade', 'textdomain' ),
+			'title' => esc_html__( 'Promotion heading', 'textdomain' ),
+			'description' => esc_html__( 'Get the premium version of the widget and grow your website capabilities.', 'textdomain' ),
+			'upgrade_url' => esc_url( 'https://example.com/upgrade-to-pro/' ),
+			'upgrade_text' => esc_html__( 'Upgrade Now', 'textdomain' ),
+		];
+	}
+
+}
+```
+
+This is the place to emphasize that the promotion is set on a specific widget. It allows addon developers to create a custom CTA to promote a premium version of that widget.
+
+There is an option to conditionally hide/display this promotion if some conditions are met. For example, Elementor uses widget promotions only when Elementor Pro is not active, therefore paying customers don't see widget promotions.

src/widgets/widget-promotions.md

@@ -54,7 +54,6 @@ The `\Elementor\Widget_Base` class has many more methods, but the vast majority
 These methods can be divided into five groups:
 
 * [Data](./widget-data/)
-* [Categories](./widget-categories/)
 * [Dependencies](./widget-dependencies/)
 * [Controls](./widget-controls/)
 * [Rendering](./widget-rendering/)