Weston Ruter

Payton Swick

<p><em>Important note:</em> This project was first started before the Gutenberg feature plugin was started. As such, the JS Widgets plugin should now be considered a <em>prototype</em> which may inform the way that widget <em>blocks</em> get implemented in Gutenberg. This plugin will no longer be actively developed.</p>
<p>Also could be known as Widget Customizer 2.0, Widgets 3.0, or Widgets Next Generation.</p>
<p><em>Warning:</em> The APIs provided by this plugin are still in flux. If creating new widgets that extend the <code>WP_JS_Widget</code> class, please look at the changelog and ensure compatibility with your extended widgets before deploying.</p>
<p>This plugin implements:</p>
<ul>
<li><a href="https://core.trac.wordpress.org/ticket/33507" rel="nofollow ugc">WP-CORE#33507</a>: Allow widget controls to be JS-driven.</li>
<li><a href="https://core.trac.wordpress.org/ticket/35574" rel="nofollow ugc">WP-CORE#35574</a>: Add REST API JSON schema information to WP_Widget.</li>
<li><a href="https://github.com/WP-API/WP-API/issues/19" rel="nofollow ugc">WP-API#19</a>: Add widget endpoints to the WP REST API.</li>
</ul>
<p>Features:</p>
<ul>
<li>Integrates with <a href="https://wordpress.org/plugins/shortcode-ui/" rel="ugc">Shortcake (Shortcode UI)</a> to allow all JS widgets to be made available as Post Elements in the editor.</li>
<li>Widget instance settings in the Customizer are exported from PHP as regular JSON without any PHP-serialized base64-encoded <code>encoded_serialized_instance</code> anywhere to be seen.</li>
<li>Previewing widget changes in the customizer is faster since the <code>update-widget</code> Ajax request can be eliminated since the JS control can directly manipulate the widget instance data.</li>
<li>Widgets control forms use JS content templates instead of PHP to render the markup for each control, reducing the weight of the customizer load, especially when there are a lot of widgets in use.</li>
<li>Widgets that extend <code>WP_JS_Widget</code> will editable from both the customizer and the widgets admin page using the same <code>Form</code> JS interface. This <code>Form</code> is also able to be embedded in other contexts, like on the frontend and as a Shortcake (Shortcode UI) form. See <a href="https://github.com/xwp/wp-js-widgets/issues/11" rel="nofollow ugc">#11</a>.</li>
<li>Widgets employ the JSON Schema from the REST API to define an instance with validation and sanitization of the instance properties, beyond also providing <code>validate</code> and <code>sanitize</code> methods that work on the instance array as a whole.</li>
<li>A widget instance can be blocked from being saved by returning a <code>WP_Error</code> from its <code>validate</code> or <code>sanitize</code> method. For example, the RSS widget will show an error message if the feed URL provided is invalid and the widget will block from saving until the URL is corrected.</li>
<li>Widgets are exposed under the <code>js-widgets/v1</code> namespace, for example to list all Recent Posts widgets via the <code>/js-widgets/v1/widgets/recent-posts</code> or to get the Text widget with the “ID” (number) of 6, <code>/js-widgets/v1/widgets/text/6</code>.</li>
<li>Customizer settings for widget instances (<code>widget_{id_base}[{number}]</code>) are directly mutated via JavaScript instead of needing to do an <code>update-widget</code> Admin Ajax roundtrip; this greatly speeds up previewing.</li>
<li>Widget control forms can be extended to employ any JS framework for managing the UI, allowing Backbone, React, or any other frontend technology to be used.</li>
<li>Compatible with widgets stored in a custom post type instead of options, via the Widget Posts module in the <a href="https://github.com/xwp/wp-customize-widgets-plus" rel="nofollow ugc">Customize Widgets Plus</a> plugin.</li>
<li>Compatible with <a href="https://github.com/xwp/wp-customize-snapshots" rel="nofollow ugc">Customize Snapshots</a>, allowing changes made in the Customizer to be applied to requests for widgets via the REST API.</li>
<li>Includes adaptations of all core widgets using the new <code>WP_JS_Widget</code> API.</li>
<li>The adapted core widgets include additional raw data in their REST API item responses so that JS can render them client-side.</li>
<li>The Notifications API is utilized to display warnings when a user attempts to provide markup in a core widget title or illegal HTML in a Text widget’s content.</li>
<li>The Pages widget in Core is enhanced to make use of <a href="https://wordpress.org/plugins/customize-object-selector/" rel="ugc">Customize Object Selector</a> if available to display a Select2 UI for selecting pages to exclude instead of providing page IDs.</li>
<li>An bonus bundled plugin provides a “Post Collection” widget which, if the <a href="https://wordpress.org/plugins/customize-object-selector/" rel="ugc">Customize Object Selector</a> plugin is installed, will provide a UI for curating an arbitrary list of posts to display.</li>
</ul>
<p>This plugin doesn’t yet implement any widgets that use JS templating for <em>frontend</em> rendering of the widgets. For that, please see the <a href="https://github.com/xwp/wp-next-recent-posts-widget" rel="nofollow ugc">Next Recent Posts Widget</a> plugin.</p>
<p>Limitations/Caveats:</p>
<ul>
<li>Only widgets that extend <code>WP_JS_Widget</code> will be exposed via the REST API. The plugin includes a <code>WP_JS_Widget</code> adapter class which demonstrates how to adapt existing <code>WP_Widget</code> classes for the new widget functionality.</li>
</ul>


JS Widgets

A prototype of next generation of widgets in core, embracing JS for UI and powering the Widgets REST API.

George Stephanis

Brandon Kraft

Kaspars

Derek Herman

Arslan Kalwar

<p><strong>⚠️ IMPORTANT: This plugin has been merged into WordPress core version 5.6 and doesn’t have to be installed separately. <a href="https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/" rel="nofollow ugc">View the integration guide <span aria-hidden="true" class="wp-exclude-emoji">→</span></a></strong></p>
<p>Use Application Passwords to authenticate users without providing their passwords directly. Instead, a unique password is generated for each application without revealing the user’s main password. Application passwords can be revoked for each application individually.</p>
<p><strong>Important:</strong> Application Passwords can be used only for authenticating API requests such as <a href="https://developer.wordpress.org/rest-api/" rel="nofollow ugc">REST API</a> and <a href="https://codex.wordpress.org/XML-RPC_WordPress_API" rel="nofollow ugc">XML-RPC</a>, and they won’t work for regular site logins.</p>
<h4>Contribute</h4>
<ul>
<li>Translate the plugin <a href="https://translate.wordpress.org/projects/wp-plugins/application-passwords/" rel="nofollow ugc">into your language</a>.</li>
<li>Report issues, suggest features and contribute code <a href="https://github.com/WordPress/application-passwords" rel="nofollow ugc">on GitHub</a>.</li>
</ul>
<h4>Creating Application Password Manually</h4>
<ol>
<li>Go the User Profile page of the user that you want to generate a new application password for.  To do so, click <em>Users</em> on the left side of the WordPress admin, then click on the user that you want to manage.</li>
<li>Scroll down until you see the Application Passwords section.  This is typically at the bottom of the page.</li>
<li>Within the input field, type in a name for your new application password, then click <em>Add New</em>.<br />
<strong>Note:</strong> The application password name is only used to describe your password for easy management later.  It will not affect your password in any way.  Be descriptive, as it will lead to easier management if you ever need to change it later.</li>
<li>Once the <em>Add New</em> button is clicked, your new application password will appear.  Be sure to keep this somewhere safe, as it will not be displayed to you again.  If you lose this password, it cannot be obtained again.</li>
</ol>
<h4>Two Factor Support</h4>
<p>Application Passwords can be used together with the <a href="https://wordpress.org/plugins/two-factor/" rel="ugc">Two Factor plugin</a> as long as you bypass the API acccess restrictions added by the Two Factor plugin. Those protections disable API requests with password authentication <em>for users with Two Factor enabled</em>.</p>
<p>Use the <code>two_factor_user_api_login_enable</code> filter to allow API requests authenticated using an application passwords:</p>
<pre><code>add_filter( 'two_factor_user_api_login_enable', function( $enable ) {
    // Allow API login when using an application password even with 2fa enabled.
    if ( did_action( 'application_password_did_authenticate' ) ) {
        return true;
    }

    return $enable;
} );
</code></pre>
<p>This is not required if the user associated with the application password doesn’t have any of the Two Factor methods enabled.</p>
<h4>Requesting Password for Application</h4>
<p>To request a password for your application, redirect users to:</p>
<pre><code>https://example.com/wp-admin/admin.php?page=auth_app
</code></pre>
<p>and use the following <code>GET</code> request parameters to specify:</p>
<ul>
<li><code>app_name</code> (required) – The human readable identifier for your app. This will be the name of the generated application password, so structure it like … “WordPress Mobile App on iPhone 12” for uniqueness between multiple versions. If omitted, the user will be required to provide an application name.</li>
<li><code>success_url</code> (recommended) – The URL that you’d like the user to be sent to if they approve the connection. Two GET variables will be appended when they are passed back — <code>user_login</code> and <code>password</code> — these credentials can then be used for API calls. If the <code>success_url</code> variable is omitted, a password will be generated and displayed to the user, to manually enter into your application.</li>
<li><code>reject_url</code> (optional) – If included, the user will get sent there if they reject the connection. If omitted, the user will be sent to the <code>success_url</code>, with <code>?success=false</code> appended to the end. If the <code>success_url</code> is omitted, the user will be sent to their dashboard.</li>
</ul>
<h4>Testing an Application Password</h4>
<p>We use <a href="https://curl.haxx.se" rel="nofollow ugc">curl</a> to send HTTP requests to the API endpoints in the examples below.</p>
<h4>WordPress REST API</h4>
<p>Make a REST API call to update a post. Because you are performing a <code>POST</code> request, you will need to authorize the request using your newly created base64 encoded access token. If authorized correctly, you will see the post title update to “New Title.”</p>
<pre><code>curl --user "USERNAME:APPLICATION_PASSWORD" -X POST -d "title=New Title" https://LOCALHOST/wp-json/wp/v2/posts/POST_ID
</code></pre>
<p>When running this command, be sure to replace <code>USERNAME</code> and <code>APPLICATION_PASSWORD</code> with your credentials (curl takes care of base64 encoding and setting the <code>Authorization</code> header), <code>LOCALHOST</code> with the hostname of your WordPress installation, and <code>POST_ID</code> with the ID of the post that you want to edit.</p>
<h4>XML-RPC</h4>
<p>Unlike the WordPress REST API, XML-RPC does not require your username and password to be base64 encoded. Send an XML-RPC request to list all users:</p>
<pre><code>curl -H 'Content-Type: text/xml' -d '<methodCall><methodName>wp.getUsers</methodName><params><param><value>1</value></param><param><value>USERNAME</value></param><param><value>PASSWORD</value></param></params></methodCall>' https://LOCALHOST/xmlrpc.php
</code></pre>
<p>In the above example, replace <code>USERNAME</code> with your username, <code>PASSWORD</code> with your new application password, and <code>LOCALHOST</code> with the hostname of your WordPress installation. This should output a response containing all users on your site.</p>
<h4>Plugin History</h4>
<p>This is a feature plugin that is a spinoff of the main <a href="https://github.com/WordPress/two-factor/" rel="nofollow ugc">Two-Factor Authentication plugin</a>.</p>


Application Passwords

Straightforward and nicely executed. Thank you for creating this. 

Excellent

This plugin saved me a bunch of time and concern when trying to lock down a couple of scripts. I was initially concerned that I was going to be in for some hoop-jumping to get it set up. But once I jumped in, I had it working in no time.

Simple setup, super handy!

Creates unique passwords for applications to authenticate users without revealing their main passwords.

JS Widgets vs Application Passwords