resources/src/mediawiki.api/edit.js

   1 /**
   2  * @class mw.Api.plugin.edit
   3  */
   4 ( function () {
   5
   6         $.extend( mw.Api.prototype, {
   7
   8                 /**
   9                  * Post to API with csrf token. If we have no token, get one and try to post.
  10                  * If we have a cached token try using that, and if it fails, blank out the
  11                  * cached token and start over.
  12                  *
  13                  * @param {Object} params API parameters
  14                  * @param {Object} [ajaxOptions]
  15                  * @return {jQuery.Promise} See #post
  16                  */
  17                 postWithEditToken: function ( params, ajaxOptions ) {
  18                         return this.postWithToken( 'csrf', params, ajaxOptions );
  19                 },
  20
  21                 /**
  22                  * API helper to grab a csrf token.
  23                  *
  24                  * @return {jQuery.Promise} Received token.
  25                  */
  26                 getEditToken: function () {
  27                         return this.getToken( 'csrf' );
  28                 },
  29
  30                 /**
  31                  * Create a new page.
  32                  *
  33                  * Example:
  34                  *
  35                  *     new mw.Api().create( 'Sandbox',
  36                  *         { summary: 'Load sand particles.' },
  37                  *         'Sand.'
  38                  *     );
  39                  *
  40                  * @since 1.28
  41                  * @param {mw.Title|string} title Page title
  42                  * @param {Object} params Edit API parameters
  43                  * @param {string} params.summary Edit summary
  44                  * @param {string} content
  45                  * @return {jQuery.Promise} API response
  46                  */
  47                 create: function ( title, params, content ) {
  48                         return this.postWithEditToken( $.extend( {
  49                                 action: 'edit',
  50                                 title: String( title ),
  51                                 text: content,
  52                                 formatversion: '2',
  53
  54                                 // Protect against errors and conflicts
  55                                 assert: mw.config.get( 'wgUserName' ) ? 'user' : undefined,
  56                                 createonly: true
  57                         }, params ) ).then( function ( data ) {
  58                                 return data.edit;
  59                         } );
  60                 },
  61
  62                 /**
  63                  * Edit an existing page.
  64                  *
  65                  * To create a new page, use #create() instead.
  66                  *
  67                  * Simple transformation:
  68                  *
  69                  *     new mw.Api()
  70                  *         .edit( 'Sandbox', function ( revision ) {
  71                  *             return revision.content.replace( 'foo', 'bar' );
  72                  *         } )
  73                  *         .then( function () {
  74                  *             console.log( 'Saved! ');
  75                  *         } );
  76                  *
  77                  * Set save parameters by returning an object instead of a string:
  78                  *
  79                  *     new mw.Api().edit(
  80                  *         'Sandbox',
  81                  *         function ( revision ) {
  82                  *             return {
  83                  *                 text: revision.content.replace( 'foo', 'bar' ),
  84                  *                 summary: 'Replace "foo" with "bar".',
  85                  *                 assert: 'bot',
  86                  *                 minor: true
  87                  *             };
  88                  *         }
  89                  *     )
  90                  *     .then( function () {
  91                  *         console.log( 'Saved! ');
  92                  *     } );
  93                  *
  94                  * Transform asynchronously by returning a promise.
  95                  *
  96                  *     new mw.Api()
  97                  *         .edit( 'Sandbox', function ( revision ) {
  98                  *             return Spelling
  99                  *                 .corrections( revision.content )
 100                  *                 .then( function ( report ) {
 101                  *                     return {
 102                  *                         text: report.output,
 103                  *                         summary: report.changelog
 104                  *                     };
 105                  *                 } );
 106                  *         } )
 107                  *         .then( function () {
 108                  *             console.log( 'Saved! ');
 109                  *         } );
 110                  *
 111                  * @since 1.28
 112                  * @param {mw.Title|string} title Page title
 113                  * @param {Function} transform Callback that prepares the edit
 114                  * @param {Object} transform.revision Current revision
 115                  * @param {string} transform.revision.content Current revision content
 116                  * @param {string|Object|jQuery.Promise} transform.return New content, object with edit
 117                  *  API parameters, or promise providing one of those.
 118                  * @return {jQuery.Promise} Edit API response
 119                  */
 120                 edit: function ( title, transform ) {
 121                         var basetimestamp, curtimestamp,
 122                                 api = this;
 123
 124                         title = String( title );
 125
 126                         return api.get( {
 127                                 action: 'query',
 128                                 prop: 'revisions',
 129                                 rvprop: [ 'content', 'timestamp' ],
 130                                 titles: [ title ],
 131                                 formatversion: '2',
 132                                 curtimestamp: true
 133                         } )
 134                                 .then( function ( data ) {
 135                                         var page, revision;
 136                                         if ( !data.query || !data.query.pages ) {
 137                                                 return $.Deferred().reject( 'unknown' );
 138                                         }
 139                                         page = data.query.pages[ 0 ];
 140                                         if ( !page || page.invalid ) {
 141                                                 return $.Deferred().reject( 'invalidtitle' );
 142                                         }
 143                                         if ( page.missing ) {
 144                                                 return $.Deferred().reject( 'nocreate-missing' );
 145                                         }
 146                                         revision = page.revisions[ 0 ];
 147                                         basetimestamp = revision.timestamp;
 148                                         curtimestamp = data.curtimestamp;
 149                                         return transform( {
 150                                                 timestamp: revision.timestamp,
 151                                                 content: revision.content
 152                                         } );
 153                                 } )
 154                                 .then( function ( params ) {
 155                                         var editParams = typeof params === 'object' ? params : { text: String( params ) };
 156                                         return api.postWithEditToken( $.extend( {
 157                                                 action: 'edit',
 158                                                 title: title,
 159                                                 formatversion: '2',
 160
 161                                                 // Protect against errors and conflicts
 162                                                 assert: mw.config.get( 'wgUserName' ) ? 'user' : undefined,
 163                                                 basetimestamp: basetimestamp,
 164                                                 starttimestamp: curtimestamp,
 165                                                 nocreate: true
 166                                         }, editParams ) );
 167                                 } )
 168                                 .then( function ( data ) {
 169                                         return data.edit;
 170                                 } );
 171                 },
 172
 173                 /**
 174                  * Post a new section to the page.
 175                  *
 176                  * @see #postWithEditToken
 177                  * @param {mw.Title|string} title Target page
 178                  * @param {string} header
 179                  * @param {string} message wikitext message
 180                  * @param {Object} [additionalParams] Additional API parameters, e.g. `{ redirect: true }`
 181                  * @return {jQuery.Promise}
 182                  */
 183                 newSection: function ( title, header, message, additionalParams ) {
 184                         return this.postWithEditToken( $.extend( {
 185                                 action: 'edit',
 186                                 section: 'new',
 187                                 title: String( title ),
 188                                 summary: header,
 189                                 text: message
 190                         }, additionalParams ) );
 191                 }
 192         } );
 193
 194         /**
 195          * @class mw.Api
 196          * @mixins mw.Api.plugin.edit
 197          */
 198
 199 }() );