Commit Graph

21 Commits

Author SHA1 Message Date
Sergey Biryukov 2a0489ec49 Docs: Replace `@returns` tags in JS docs with `@return`.
Per the documentation standards, `@returns` is an unsupported synonym, `@return` should be used instead:
https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/

See #48303.
Built from https://develop.svn.wordpress.org/trunk@46800


git-svn-id: http://core.svn.wordpress.org/trunk@46600 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2019-11-29 18:01:03 +00:00
atimmer bde558be2f Docs: Add file doc `@output` annotations.
These annotations make it clear to the reader of a JavaScript source
where the build process outputs to. These annotations can later be
integrated in a webpack configuration. This way there is one source of
truth.

The `build` folder is omitted from the paths, because a single JS file
shouldn't not be responsible of knowing where outputs in general will
end up at. A file only knows its output location relative to the
project.

Props adamsilverstein, herregroen, omarreiss, pento.
Fixes #44361.

Built from https://develop.svn.wordpress.org/trunk@43347


git-svn-id: http://core.svn.wordpress.org/trunk@43175 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2018-06-28 02:30:15 +00:00
Adam Silverstein 8a23b80b56 Docs: JSDoc improvements for namespaces.
Improve JS parsing of our inline JSDocs by introducing `@namespace`, `@lends` and `@memberOf`. Helps set the way for showing our JavaScript documentation on developer.wordpress.org, see https://meta.trac.wordpress.org/ticket/3063.

* Define all used namespaces using @namespace.
* Correctly specify in which namespace each class is using @memberOf.
* Define each usage of the extend function as a prototype assignment using @lends.
* Some comment blocks were moved to correct the parsing of certain definitions. 

Props herregroen, atimmer, netweb, SergeyBiryukov.  
Fixes #41682.

Built from https://develop.svn.wordpress.org/trunk@41351


git-svn-id: http://core.svn.wordpress.org/trunk@41184 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-09-08 18:42:49 +00:00
Weston Ruter 9669c60397 Customize: Fix ability to shift-click on placeholder/pre-saved nav menu items in preview to focus on corresponding control.
Fixes #39102.

Built from https://develop.svn.wordpress.org/trunk@39562


git-svn-id: http://core.svn.wordpress.org/trunk@39502 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-12-10 23:47:41 +00:00
Weston Ruter 672b8a61cd Customize: Prevent infinite full refresh from occurring when selective refresh falls back for a nav menu that has items excluded from rendering via filtering.
See #37032.
Fixes #38612.

Built from https://develop.svn.wordpress.org/trunk@39510


git-svn-id: http://core.svn.wordpress.org/trunk@39450 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-12-06 02:51:42 +00:00
Weston Ruter 277d4d0ab0 Customize: Prevent selective refresh from causing infinite fallback refreshes when nav menu contains invalid items.
Invalid nav menu items are exported as settings in the customize controls since it `is_admin()`, but any such `nav_menu_item` settings are excluded from the preview since it's the frontend. Selective refresh for nav menus needs to ignore the syncing of any such `nav_menu_item` settings that are `_invalid` since they are never rendered, and when a nav menu only contains invalid items, an infinite fallback refresh can ensue.

Fixes #38890.

Built from https://develop.svn.wordpress.org/trunk@39333


git-svn-id: http://core.svn.wordpress.org/trunk@39273 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-11-21 19:16:32 +00:00
Weston Ruter 75535c596b Customize: Introduce starter content and site freshness state.
A theme can opt-in for tailored starter content to apply to the customizer when previewing the theme on a fresh install, when `fresh_site` is at its initial `1` value. Starter content is staged in the customizer and does not go live unless the changes are published. Initial starter content is added to Twenty Seventeen.

* The `fresh_site` flag is cleared when a published post or page is saved, when widgets are modified, or when the customizer state is saved.
* Starter content is registered via `starter-content` theme support, where the argument is an array containing `widgets`, `posts`, `nav_menus`, `options`, and `theme_mods`. Posts/pages in starter content are created with the `auto-draft` status, re-using the page/post stubs feature added to nav menus and the static front page controls.
* A `get_theme_starter_content` filter allows for plugins to extend a theme's starter content.
* Starter content in themes can/should re-use existing starter content items in core by using named placeholders.
* Import theme starter content into customized state when fresh site.
* Prevent original_title differences from causing refreshes if title is present.
* Ensure nav menu item url is set according to object when previewing.
* Make sure initial saved state is false if there are dirty settings without an existing changeset.
* Ensure dirty settings are cleaned upon changeset publishing.

Props helen, westonruter, ocean90.
Fixes #38114, #38533.

Built from https://develop.svn.wordpress.org/trunk@38991


git-svn-id: http://core.svn.wordpress.org/trunk@38934 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-10-28 02:57:35 +00:00
Weston Ruter f1ba1918c9 Customize: Implement customized state persistence with changesets.
Includes infrastructure developed in the Customize Snapshots feature plugin.

See https://make.wordpress.org/core/2016/10/12/customize-changesets-technical-design-decisions/

Props westonruter, valendesigns, utkarshpatel, stubgo, lgedeon, ocean90, ryankienstra, mihai2u, dlh, aaroncampbell, jonathanbardo, jorbin.
See #28721.
See #31089.
Fixes #30937.
Fixes #31517.
Fixes #30028.
Fixes #23225.
Fixes #34142.
Fixes #36485.

Built from https://develop.svn.wordpress.org/trunk@38810


git-svn-id: http://core.svn.wordpress.org/trunk@38753 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-10-18 20:05:31 +00:00
Weston Ruter e11fd98ec6 Customize: Fix regressions and harden implementation of selective refresh for nav menus.
* Request full refresh if there are nav menu instances that lack partials for a changed setting.
* Restore `WP_Customize_Nav_Menus::$preview_nav_menu_instance_args` and `WP_Customize_Nav_Menus::export_preview_data()` from 4.3, and keeping a tally of all `wp_nav_menu()` calls regardless of whether they can use selective refresh.
* Ensure that all instances of `wp_nav_menu()` are tallied, regardless of whether they are made during the initial preview call or during subsequent partial renderings. Export `nav_menu_instance_args` with each partial rendering response just as they are returned when rendering the preview as a whole.
* Fix issues with Custom Menu widget where nav menu items would fail to render when switching between menus when a menu lacked items to begin with.
* Make sure the fallback behavior is invoked when the partial is no longer associated with a menu.
* Do fallback behavior to refresh preview when all menu items are removed from a menu.

Follows [36586].
See #27355.
Fixes #35362.

Built from https://develop.svn.wordpress.org/trunk@36889


git-svn-id: http://core.svn.wordpress.org/trunk@36856 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-03-09 00:09:26 +00:00
Weston Ruter 6b775d4afe Customize: Add selective refresh framework with implementation for widgets and re-implementation for nav menus.
See https://make.wordpress.org/core/2016/02/16/selective-refresh-in-the-customizer/.

Props westonruter, valendesigns, DrewAPicture, ocean90.
Fixes #27355.

Built from https://develop.svn.wordpress.org/trunk@36586


git-svn-id: http://core.svn.wordpress.org/trunk@36553 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-02-19 18:41:28 +00:00
Weston Ruter 9343641855 Customize: Ensure that nav menu items can be shift-clicked to edit in secondary instances of the same nav menu.
When the same nav menu is shown multiple times on a page, only the first instance of the nav menu will include `id` attributes. Subsequent instances will have the `id` attributes omitted. However, in both cases the underlying nav menu item's post ID is available among the `class` names, so the post ID can be more reliably obtained from `class` instead of the `id` attribute.  

Amends [36383].
Fixes #32681.

Built from https://develop.svn.wordpress.org/trunk@36523


git-svn-id: http://core.svn.wordpress.org/trunk@36490 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-02-13 00:12:25 +00:00
Weston Ruter c376477265 Customizer: Export `nonce`, `theme`, and `url` app settings in preview as exported in pane.
* Introduce `WP_Customize_Manager::get_nonces()` to consolidate logic for retrieving nonces.
* Export nonces centrally in `wp.customize.settings.nonce` with each request and update nav menus preview to utilize.
* Send updated nonces to preview upon `nonce-refresh`.
* Request full preview refresh if Nav Menu selective refresh request fails (e.g. due to bad nonce).
* Update nav menus and widgets in Customizer to utilize `customize_refresh_nonces` for exporting nonces and keeping them up to date.

See #27355.
Fixes #35617.

Built from https://develop.svn.wordpress.org/trunk@36414


git-svn-id: http://core.svn.wordpress.org/trunk@36381 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-01-27 17:55:26 +00:00
Weston Ruter fb8544a0ac Customizer: Add shift-click on nav menu items in preview to focus on corresponding nav menu item controls in pane.
Add missing `params.completeCallback` to `MenuItemControl.focus()` for parity with `Control.focus()`. Also adds `params` to `MenuItemControl.expandForm`, `MenuItemControl.collapseForm()`, and `MenuItemControl.toggleForm()`.

Props MattGeri, westonruter.
Fixes #32681.

Built from https://develop.svn.wordpress.org/trunk@36383


git-svn-id: http://core.svn.wordpress.org/trunk@36350 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-01-22 21:21:26 +00:00
Weston Ruter 49b3ad2251 Twenty Fifteen: Only re-initialize the main navigation in the Customizer when it is specifically updated.
* Fix a bug where updating the social menu links would cause the main navigation to get its toggle-expanded buttons duplicated.
* Persist any existing submenu expanded states on the updated menu. 
* Improve naming of `customize-preview-menu-refreshed` event param from `wpNavArgs` to `wpNavMenuArgs` (old name is retained and marked as deprecated).

Fixes #33177.

Built from https://develop.svn.wordpress.org/trunk@33491


git-svn-id: http://core.svn.wordpress.org/trunk@33458 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-07-29 18:13:24 +00:00
Scott Taylor 23712a822f Customizer: Nav Menus JS cleanup, second round
* Follow the same pattern of namespace instantiation that `WidgetCustomizerPreview` uses
* Remove use of `self` for global delegation
* Use `api` for `wp.customize` and import only top-level globals
* Bind `this` where appropriate and disambiguate scope

See #32911.

Built from https://develop.svn.wordpress.org/trunk@33347


git-svn-id: http://core.svn.wordpress.org/trunk@33319 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-07-21 17:40:25 +00:00
Scott Taylor 4e8fc7b69c Customizer: Nav Menus JS cleanup, first round
* In `init`, settings should be fresh and set to default values before extending
* When looping via `_.each`, pass `this` as 3rd arg to bind context
* Settings should be encapsulated in the module, instead of being exposed as static class props
* `currentRefreshMenuInstanceDebouncedCalls` should be encapsulated and renamed, instead of being the longest symbol in the entire codebase

See #32911.

Built from https://develop.svn.wordpress.org/trunk@33345


git-svn-id: http://core.svn.wordpress.org/trunk@33317 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-07-21 16:14:24 +00:00
Ella Iseulde Van Dorpe 1d92ed1c79 JSHint: don't redeclare globals listed in .jshintrc
See #33021.

Built from https://develop.svn.wordpress.org/trunk@33337


git-svn-id: http://core.svn.wordpress.org/trunk@33309 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-07-20 23:39:24 +00:00
Weston Ruter 8041554b30 Customizer: Fix previewing certain changes to nav menus.
Addresses regression introduced in [33138], where deleted menu items would not be removed from the preview, and changes to a location's assigned menu would likewise not preview. Also makes the binding of the setting change events more robust.

Fixes #33010.


Built from https://develop.svn.wordpress.org/trunk@33328


git-svn-id: http://core.svn.wordpress.org/trunk@33300 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-07-20 07:44:26 +00:00
Weston Ruter 3e58b38b28 Customizer: Remove additional wrapper element around `wp_nav_menu()` which broke some theme designs.
Also includes these related changes:
* Export `oldContainer` and `newContainer` among the `customize-preview-menu-refreshed` event params for themes to be able to more easily re-initialize the DOM elements.
* Improve performance for partial refresh by only sending settings related to the menu being previewed.
* Fix previewing of menu assigned to Custom Menu by exporting a menu `term_id` as opposed to an object, as the former is more stable for comparing in in args hashes.
* Do full refresh of preview when nav menu unassigned so that the layout can be updated.
* Harden conditions for when partial refresh is eligible for a `wp_nav_menu()` instance.

Fixes #32841.

Built from https://develop.svn.wordpress.org/trunk@33138


git-svn-id: http://core.svn.wordpress.org/trunk@33109 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-07-08 21:30:24 +00:00
Weston Ruter 3f64c0ee9e Customizer: Defer listening to nav menu setting changes until active.
Defer the preview starting to listen to setting changes until after the Customizer has synced settings into the preview. This ensures that any differences between the JS and PHP representations of the settings won't cause an infinite refresh.

See #32911.
Fixes #32894.

Built from https://develop.svn.wordpress.org/trunk@33134


git-svn-id: http://core.svn.wordpress.org/trunk@33105 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-07-08 20:42:24 +00:00
Dominik Schilling 62e3a0c15c Add menu management to the Customizer.
This brings in the Menu Customizer plugin: https://wordpress.org/plugins/menu-customizer/.

props celloexpressions, westonruter, valendesigns, voldemortensen, ocean90, adamsilverstein, kucrut, jorbin, designsimply, afercia, davidakennedy, obenland.
see #32576.
Built from https://develop.svn.wordpress.org/trunk@32806


git-svn-id: http://core.svn.wordpress.org/trunk@32777 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-06-16 22:08:26 +00:00