Commit Graph

29 Commits

Author SHA1 Message Date
Sergey Biryukov
6307a7c41c Docs: Correct alignment for some parameters in JS documentation.
Follow-up to [48650].

See #43828.
Built from https://develop.svn.wordpress.org/trunk@48651


git-svn-id: http://core.svn.wordpress.org/trunk@48413 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-07-28 00:07:03 +00:00
whyisjake
3dd9628aae Build/Test Tools: Enable JSDocs to be linted with ESLint.
As part of the [Javascript Inline Docs Initiative](https://make.wordpress.org/core/handbook/docs/inline/js/) this add some tooling to lint Javascript docblocks. Two new commands:

* `npm run lint:jsdoc`
* `npm run lint:jsdoc:fix`

The latter will run the linter and try to fix an possible issues automatically.

Fixes #43828.
Props netweb, atimmer, kamataryo, whyisjake.


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


git-svn-id: http://core.svn.wordpress.org/trunk@48412 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-07-27 23:35:02 +00:00
Sergey Biryukov
be16bb9fba Docs: Remove extra spaces from @param tags.
Per the documentation standards, `@param` tags should be aligned with each other, but not with the `@return` tag.

See #49572.
Built from https://develop.svn.wordpress.org/trunk@48110


git-svn-id: http://core.svn.wordpress.org/trunk@47879 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-06-20 12:58:10 +00:00
Sergey Biryukov
3fb623cf76 Docs: Use a hyphen with the "non" prefix in a more consistent way.
See #49572.
Built from https://develop.svn.wordpress.org/trunk@48106


git-svn-id: http://core.svn.wordpress.org/trunk@47875 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-06-20 12:16:10 +00:00
Sergey Biryukov
e13c363b17 Docs: Capitalize "ID", when referring to a post ID, term ID, etc. in a more consistent way.
See #49572.
Built from https://develop.svn.wordpress.org/trunk@48104


git-svn-id: http://core.svn.wordpress.org/trunk@47873 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-06-20 12:02:12 +00:00
Sergey Biryukov
001ffe81fb Docs: Improve inline comments per the documentation standards.
Includes minor code layout fixes for better readability.

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


git-svn-id: http://core.svn.wordpress.org/trunk@46922 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-01-29 00:45:18 +00:00
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
K. Adam White
b5ec1e6d96 REST API: generate a valid fallback URI in wp.api.utils.getRootURL.
When window.location.origin isn't set, correctly insert two slashes between the protocol and host when constructing the fallback URL.

props abdullahramzan.
Fixes #44764.

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


git-svn-id: http://core.svn.wordpress.org/trunk@43395 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2018-08-11 18:51:24 +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
Dominik Schilling
6fd9d2edcf REST API JavaScript Client: Support an empty string for nonce to disable sending the X-WP-Nonce header.
Passing a `nonce` argument with an empty string to `wp.api.init()` now does no longer fall back to `wpApiSettings.nonce`. This makes it possible to stop sending nonce headers, for example to a read-only endpoint on another site in a multisite install.

Props adamsilverstein, FPCSJames, ocean90, swissspidy.
Fixes #42948, #43266.
Built from https://develop.svn.wordpress.org/trunk@42852


git-svn-id: http://core.svn.wordpress.org/trunk@42682 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2018-03-18 17:21:30 +00:00
Dominik Schilling
3138d89e1e REST API JS Client: Extend custom nonce functionality to collections.
This brings the improved nonce handling from [41553] to collections to remove the direct `wpApiSettings.nonce` dependency.

Props adamsilverstein, ocean90, swissspidy.
Fixes #43265.
Built from https://develop.svn.wordpress.org/trunk@42851


git-svn-id: http://core.svn.wordpress.org/trunk@42681 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2018-03-18 17:04:30 +00:00
atimmer
1f707de9dd Docs: Improve wp-admin JSDoc structural data globally.
JSDoc takes it structural data from `@namespace`, `@lends` and `@memberOf`. This change fixes these tags for all JavaScript files in the wp-admin folder.

* Add jsdoc configuration to parse wp-admin/js files. Use `jsdoc -c jsdoc.conf.json` to generate JSDoc.
* Define all used namespaces using `@namespace`.
* Define each usage of the extend function as a prototype assignment using `@lends`.
* Add `@alias` if JSDoc cannot detect the correct name automatically.

This has previously been corrected for all `wp-includes` JavaScript files: [41351].

Props herregroen.
Fixes #42485.

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


git-svn-id: http://core.svn.wordpress.org/trunk@42232 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-12-15 13:42:46 +00:00
Adam Silverstein
274792f9cd REST API: JS client - Enumerate endpoints supporting trash.
Improve the logic determining which endpoints support the trash by enumerating them. Endpoints that don't support the trash require `force=true` when deleting. The previous approach relied on the `force` argument description, which is a translated string and was fragile. In the future, we can expose whether an endpoint supports the trash as part of its schema and automate this logic.

Props Soean.
Fixes #40672.


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


git-svn-id: http://core.svn.wordpress.org/trunk@41881 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-10-31 02:54:48 +00:00
Adam Silverstein
5087d26d2d WP-API JS Client: Improve support for meta.
* Add/fix `getMeta`, `getMetas`, `setMeta` and `setMetas` helpers for models that support meta.
* Add tests for new helpers, verify meta support for `Posts`, `Comments`, `Tags` and `Users`.
* Include meta data in fixture generation and fixture file driving tests.

Fixes #41055.

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


git-svn-id: http://core.svn.wordpress.org/trunk@41512 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-10-02 18:41:35 +00:00
Adam Silverstein
e23b4e9269 REST API JavaScript Client: improve support for model deletion/trash.
Update the way and location the JavaScript client determines which models/endpoints require the `force=true` parameter when being deleted to avoid a `rest_trash_not_supported` error. Identify models with endpoints that support DELETE, excluding those that support the trash (posts and pages by default). Also, move the check into the default `wp.api.WPApiBaseModel.initialize()` function.

Props caercam, euthelup.
Fixes #40672.


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


git-svn-id: http://core.svn.wordpress.org/trunk@41491 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-10-01 13:07:45 +00:00
Adam Silverstein
639d215300 REST API JS Client: Improve nonce handling, refresh stale nonce on sync.
Keep the nonce used for cookie based authentication fresh by pulling in and using any new nonce supplied in the response headers.

* Enable passing nonce to init so each api/endpoint can use a unique nonce.
* Store nonce for endpoint on endpointModel.
* New model helper `nonce()` retrieves a model's routeModel nonce.
* When a response header contains a nonce that doesn't match the stored nonce, replace it.

Fixes #40422.

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


git-svn-id: http://core.svn.wordpress.org/trunk@41386 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-09-21 12:58:45 +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
Adam Silverstein
ba0970ab28 WP-API JS Client: Add helpers to get a model or collection by route.
Add two new helper functions, `wp.api.getModelByRoute` and `wp.api.getCollectionByRoute`. Passed a route, they return the matching model or collection, or `undefined` if none is found.

Also adds tests to verify these functions work as expected.

Props rcutmore.
Fixes #41111.

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


git-svn-id: http://core.svn.wordpress.org/trunk@41165 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-09-04 16:01:43 +00:00
K. Adam White
6aaba32b36 WP-API JS Client: Interpret Settings resource as a model.
The REST API does not provide a mechanism to distinguish between endpoints representing models and those representing collections, so the Backbone client must make that distinction internally. Previously wp-api.js accounted for `/users/me`, but not for `/settings`. This patch updates the logic so that `/settings` is properly registered as a Backbone model.

When calling `wp.api.init`, additional endpoints can be specified to be models using the `modelEndpoints` argument.

Props @adamsilverstein.
Fixes #41056.

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


git-svn-id: http://core.svn.wordpress.org/trunk@40952 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-07-20 20:26:45 +00:00
Adam Silverstein
789f141045 REST API: JS Client - Enable connecting to multiple endpoints.
Enable connecting to multiple wp-api `endpoints`. Calling `wp.api.init` with a new `apiRoot` will parse the new endpoint's schema and store a new set of models and collections. A collection of connected endpoints is stored in `wp.api.endpoints`.

Props lucasstark.
Fixes #39683.


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


git-svn-id: http://core.svn.wordpress.org/trunk@40271 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-04-02 19:41:41 +00:00
Adam Silverstein
518ff1576b REST API: JavaScript client - improve route discovery for custom namespaces.
Fix parsing of custom namespace routes. Transform class names, removing dashes and capitalizing each word/route part so a route path of `widgets/recent-posts` becomes a collection with the name `WidgetsRecentPosts`. Correct parent route part when routes are longer than expected, reversing parse direction.

Props westonruter, jazbek.
Fixes #39561.

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


git-svn-id: http://core.svn.wordpress.org/trunk@40011 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-02-17 20:54:44 +00:00
Adam Silverstein
717aeab3cc REST API: JavaScript client should use _.extend when merging objects.
Correct an issue during the client's dynamic route discovery in `wp.api.utils.decorateFromRoute` where `_.union` potentially failed if used on objects.

Props ketuchetan.
Fixes #39341.


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


git-svn-id: http://core.svn.wordpress.org/trunk@39977 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-02-03 21:46:43 +00:00
Adam Silverstein
c8a3496ebe REST API: Add error handling for fetch error in buildModelGetter of wp-api.js.
When a call to a model getter method fails, reject the returned deferred object. Enables better handling of fetch errors.

Props westonruter, adamsilverstein.
Fixes #39314.

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


git-svn-id: http://core.svn.wordpress.org/trunk@39620 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-01-05 03:03:42 +00:00
Adam Silverstein
bc7a03a33b WP-API: JavaScript client - fix setup of models used by wp.api.collections objects.
Correct setup for the `model` attribute of `wp.api.collections` objects. Set the collection model as a function that returns a new model of the underlying type, instead of setting it as the model prototype. Fixes an issue where models for fetched collections weren't set up properly and didn't have the expected mixin methods such as `getCategories` available.

Props jesseenterprises.
Fixes #39070.

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


git-svn-id: http://core.svn.wordpress.org/trunk@39543 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-12-15 12:54:42 +00:00
Joe Hoyle
e20ded7e75 REST API: Make JS Client store schema in session storage.
Props adamsilverstein.
Fixes #38895.
Built from https://develop.svn.wordpress.org/trunk@39344


git-svn-id: http://core.svn.wordpress.org/trunk@39284 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-11-23 02:55:30 +00:00
Drew Jaynes
5f4497f0af Docs: Fix multiple trivial typos throughout a variety of core files.
Props ottok.
Fixes #38489.

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


git-svn-id: http://core.svn.wordpress.org/trunk@38993 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-10-31 06:28:32 +00:00
John Blackbourn
4e65c0cfb4 REST API: Correct a documentation typo.
Props Zuige
Fixes #38458
See #38456

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


git-svn-id: http://core.svn.wordpress.org/trunk@38822 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-10-23 15:56:30 +00:00
John Blackbourn
f96940f574 REST API: Correct a documentation typo.
Props Zuige
Fixes #38458

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


git-svn-id: http://core.svn.wordpress.org/trunk@38821 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-10-23 15:52:40 +00:00
Rachel Baker
e4a7c0a397 REST API: Introduce the Content API endpoints.
REST API endpoints for your WordPress content. These endpoints provide machine-readable external access to your WordPress site with a clear, standards-driven interface, allowing new and innovative apps for interacting with your site. These endpoints support all of the following:
- Posts: Read and write access to all post data, for all types of post-based data, including pages and media.
- Comments: Read and write access to all comment data. This includes pingbacks and trackbacks.
- Terms: Read and write access to all term data.
- Users: Read and write access to all user data. This includes public access to some data for post authors.
- Meta: Read and write access to metadata for posts, comments, terms, and users, on an opt-in basis from plugins.
- Settings: Read and write access to settings, on an opt-in basis from plugins and core. This enables API management of key site content values that are technically stored in options, such as site title and byline.

Love your REST API, WordPress!  The infrastructure says, "Let's do lunch!" but the content API endpoints say, "You're paying!"

Props rmccue, rachelbaker, danielbachhuber, joehoyle, adamsilverstein, afurculita, ahmadawais, airesvsg, alisspers, antisilent, apokalyptik, artoliukkonen, attitude, boonebgorges, bradyvercher, brianhogg, caseypatrickdriscoll, chopinbach, chredd, christianesperar, chrisvanpatten, claudiolabarbera, claudiosmweb, cmmarslender, codebykat, coderkevin, codfish, codonnell822, daggerhart, danielpunkass, davidbhayes, delphinus, desrosj, dimadin, dotancohen, DrewAPicture, Dudo1985, duncanjbrown, eherman24, eivhyl, eliorivero, elyobo, en-alis, ericandrewlewis, ericpedia, evansobkowicz, fjarrett, frozzare, georgestephanis, greatislander, guavaworks, hideokamoto, hkdobrev, hubdotcom, hurtige, iandunn, ircrash, ironpaperweight, iseulde, Japh, jaredcobb, JDGrimes, jdolan, jdoubleu, jeremyfelt, jimt, jjeaton, jmusal, jnylen0, johanmynhardt, johnbillion, jonathanbardo, jorbin, joshkadis, JPry, jshreve, jtsternberg, JustinSainton, kacperszurek, kadamwhite, kalenjohnson, kellbot, kjbenk, kokarn, krogsgard, kuchenundkakao, kuldipem, kwight, lgedeon, lukepettway, mantismamita, markoheijnen, matrixik, mattheu, mauteri, maxcutler, mayukojpn, michael-arestad, miyauchi, mjbanks, modemlooper, mrbobbybryant, NateWr, nathanrice, netweb, NikV, nullvariable, oskosk, oso96_2000, oxymoron, pcfreak30, pento, peterwilsoncc, Pezzab, phh, pippinsplugins, pjgalbraith, pkevan, pollyplummer, pushred, quasel, QWp6t, schlessera, schrapel, Shelob9, shprink, simonlampen, Soean, solal, tapsboy, tfrommen, tharsheblows, thenbrent, tierra, tlovett1, tnegri, tobych, Toddses, toro_unit, traversal, vanillalounge, vishalkakadiya, wanecek, web2style, webbgaraget, websupporter, westonruter, whyisjake, wonderboymusic, wpsmith, xknown, zyphonic.
Fixes #38373.
Built from https://develop.svn.wordpress.org/trunk@38832


git-svn-id: http://core.svn.wordpress.org/trunk@38775 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-10-20 02:55:32 +00:00