module MediaWiki::Gateway::Pages

Public Instance Methods

category_members(category, options = {}) click to toggle source

Get a list of pages that are members of a category

category

Name of the category

options

Optional hash of additional options. See www.mediawiki.org/wiki/API:Categorymembers

Returns array of page titles (empty if no matches)

    # File lib/media_wiki/gateway/pages.rb
274 def category_members(category, options = {})
275   iterate_query('categorymembers', '//cm', 'title', 'cmcontinue', options.merge(
276     'cmtitle' => category,
277     'continue' => '', # new format, per https://www.mediawiki.org/wiki/API:Query#Continuing_queries
278     'cmlimit' => @options[:limit]
279   ))
280 end
create(title, content, options = {}) click to toggle source

Create a new page, or overwrite an existing one

title

Page title to create or overwrite, string

content

Content for the page, string

options

Hash of additional options

Options:

  • :overwrite

    Allow overwriting existing pages

  • :summary

    Edit summary for history, string

  • :token

    Use this existing edit token instead requesting a new one (useful for bulk loads)

  • :minor

    Mark this edit as “minor” if true, mark this edit as “major” if false, leave major/minor status by default if not specified

  • :notminor

    Mark this edit as “major” if true

  • :bot

    Set the bot parameter (see www.mediawiki.org/wiki/API:Edit#Parameters). Defaults to false.

    # File lib/media_wiki/gateway/pages.rb
 93 def create(title, content, options = {})
 94   form_data = {
 95     'action'  => 'edit',
 96     'title'   => title,
 97     'text'    => content,
 98     'summary' => options[:summary] || '',
 99     'token'   => get_token('edit', title)
100   }
101 
102   if @options[:bot] || options[:bot]
103     form_data.update('bot' => '1', 'assert' => 'bot')
104   end
105 
106   form_data['minor']      = '1' if options[:minor]
107   form_data['notminor']   = '1' if options[:minor] == false || options[:notminor]
108   form_data['createonly'] = '' unless options[:overwrite]
109   form_data['section']    = options[:section].to_s if options[:section]
110 
111   send_request(form_data)
112 end
delete(title, options = {}) click to toggle source

Delete one page. (MediaWiki API does not support deleting multiple pages at a time.)

title

Title of page to delete

options

Hash of additional options

    # File lib/media_wiki/gateway/pages.rb
224 def delete(title, options = {})
225   send_request(options.merge(
226     'action' => 'delete',
227     'title'  => title,
228     'token'  => get_token('delete', title)
229   ))
230 end
edit(title, content, options = {}) click to toggle source

Edit page

Same options as create, but always overwrites existing pages (and creates them if they don't exist already).

    # File lib/media_wiki/gateway/pages.rb
117 def edit(title, content, options = {})
118   create(title, content, { overwrite: true }.merge(options))
119 end
get(page_title, options = {}) click to toggle source

Fetch MediaWiki page in MediaWiki format. Does not follow redirects.

page_title

Page title to fetch

options

Hash of additional options

Returns content of page as string, nil if the page does not exist.

   # File lib/media_wiki/gateway/pages.rb
13 def get(page_title, options = {})
14   page = send_request(options.merge(
15     'action' => 'query',
16     'prop'   => 'revisions',
17     'rvprop' => 'content',
18     'titles' => page_title
19   )).elements['query/pages/page']
20 
21   page.elements['revisions/rev'].text || '' if valid_page?(page)
22 end
list(key, options = {}) click to toggle source

Get a list of matching page titles in a namespace

key

Search key, matched as a prefix (^key.*). May contain or equal a namespace, defaults to main (namespace 0) if none given.

options

Optional hash of additional options, eg. { 'apfilterredir' => 'nonredirects' }. See www.mediawiki.org/wiki/API:Allpages

Returns array of page titles (empty if no matches)

    # File lib/media_wiki/gateway/pages.rb
256 def list(key, options = {})
257   key, namespace = key.split(':', 2).reverse
258   namespace = namespaces_by_prefix[namespace] || 0
259 
260   iterate_query('allpages', '//p', 'title', 'apfrom', options.merge(
261     'list'        => 'allpages',
262     'apprefix'    => key,
263     'apnamespace' => namespace,
264     'aplimit'     => @options[:limit]
265   ))
266 end
move(from, to, options = {}) click to toggle source

Move a page to a new title

from

Old page name

to

New page name

options

Hash of additional options

Options:

  • :movesubpages

    Move associated subpages

  • :movetalk

    Move associated talkpages

  • :noredirect

    Do not create a redirect page from old name. Requires the 'suppressredirect' user right, otherwise MW will silently ignore the option and create the redirect anyway.

  • :reason

    Reason for move

  • :watch

    Add page and any redirect to watchlist

  • :unwatch

    Remove page and any redirect from watchlist

    # File lib/media_wiki/gateway/pages.rb
209 def move(from, to, options = {})
210   validate_options(options, %w[movesubpages movetalk noredirect reason watch unwatch])
211 
212   send_request(options.merge(
213     'action' => 'move',
214     'from'   => from,
215     'to'     => to,
216     'token'  => get_token('move', from)
217   ))
218 end
protect(title, protections, options = {}) click to toggle source

Protect/unprotect a page

Arguments:

  • title

    Page title to protect, string

  • protections

    Protections to apply, hash or array of hashes

    Protections:

    • :action

      (required) The action to protect, string

    • :group

      (required) The group allowed to perform the action, string

    • :expiry

      The protection expiry as a GNU timestamp, string

  • options

    Hash of additional options

    Options:

    • :cascade

      Protect pages included in this page, boolean

    • :reason

      Reason for protection, string

Examples:

  1. mw.protect('Main Page', {:action => 'edit', :group => 'all'}, {:cascade => true})

  2. prt = [{:action => 'move', :group => 'sysop', :expiry => 'never'},

    {:action => 'edit', :group => 'autoconfirmed', :expiry => 'next Monday 16:04:57'}]

    mw.protect('Main Page', prt, {:reason => 'awesomeness'})

    # File lib/media_wiki/gateway/pages.rb
144 def protect(title, protections, options = {})
145   case protections
146     when Array
147       # ok
148     when Hash
149       protections = [protections]
150     else
151       raise ArgumentError, "Invalid type '#{protections.class}' for protections"
152   end
153 
154   valid_prt_options    = %w[action group expiry]
155   required_prt_options = %w[action group]
156 
157   p, e = [], []
158 
159   protections.each { |prt|
160     existing_prt_options = []
161 
162     prt.each_key { |opt|
163       if valid_prt_options.include?(opt.to_s)
164         existing_prt_options << opt.to_s
165       else
166         raise ArgumentError, "Unknown option '#{opt}' for protections"
167       end
168     }
169 
170     required_prt_options.each { |opt|
171       unless existing_prt_options.include?(opt)
172         raise ArgumentError, "Missing required option '#{opt}' for protections"
173       end
174     }
175 
176     p << "#{prt[:action]}=#{prt[:group]}"
177     e << (prt.key?(:expiry) ? prt[:expiry].to_s : 'never')
178   }
179 
180   validate_options(options, %w[cascade reason])
181 
182   form_data = {
183     'action'      => 'protect',
184     'title'       => title,
185     'token'       => get_token('protect', title),
186     'protections' => p.join('|'),
187     'expiry'      => e.join('|')
188   }
189 
190   form_data['cascade'] = '' if options[:cascade] == true
191   form_data['reason']  = options[:reason].to_s if options[:reason]
192 
193   send_request(form_data)
194 end
purge(page_titles, options = {}) click to toggle source

Purge MediaWiki page. Does not follow redirects.

page_titles

Page titles to purge

options

Hash of additional options

Returns purge object

    # File lib/media_wiki/gateway/pages.rb
351 def purge(page_titles, options = {})
352   page = send_request(options.merge(
353     'action' => 'purge',
354     'titles' => page_titles
355   ))
356 end
redirect?(page_title) click to toggle source

Checks if page is a redirect.

page_title

Page title to fetch

Returns true if the page is a redirect, false if it is not or the page does not exist.

    # File lib/media_wiki/gateway/pages.rb
302 def redirect?(page_title)
303   page = send_request(
304     'action' => 'query',
305     'prop'   => 'info',
306     'titles' => page_title
307   ).elements['query/pages/page']
308 
309   !!(valid_page?(page) && page.attributes['redirect'])
310 end
render(page_title, options = {}) click to toggle source

Render a MediaWiki page as HTML

page_title

Page title to fetch

options

Hash of additional options

Options:

  • :linkbase

    supply a String to prefix all internal (relative) links with. '/wiki/' is assumed to be the base of a relative link

  • :noeditsections

    strips all edit-links if set to true

  • :noimages

    strips all img tags from the rendered text if set to true

Returns rendered page as string, or nil if the page does not exist

   # File lib/media_wiki/gateway/pages.rb
53 def render(page_title, options = {})
54   form_data = { 'action' => 'parse', 'page' => page_title }
55 
56   validate_options(options, %w[linkbase noeditsections noimages])
57 
58   rendered, parsed = nil, send_request(form_data).elements['parse']
59 
60   if parsed.attributes['revid'] != '0'
61     rendered = parsed.elements['text'].text.gsub(/<!--(.|\s)*?-->/, '')
62 
63     # OPTIMIZE: unifiy the keys in +options+ like symbolize_keys! but w/o
64     if linkbase = options['linkbase'] || options[:linkbase]
65       rendered = rendered.gsub(/\shref="\/wiki\/([\w\(\)\-\.%:,]*)"/, ' href="' + linkbase + '/wiki/\1"')
66     end
67 
68     if options['noeditsections'] || options[:noeditsections]
69       rendered = rendered.gsub(/<span class="editsection">\[.+\]<\/span>/, '')
70     end
71 
72     if options['noimages'] || options[:noimages]
73       rendered = rendered.gsub(/<img.*\/>/, '')
74     end
75   end
76 
77   rendered
78 end
review(title, flags, comment = 'Reviewed by MediaWiki::Gateway', options = {}) click to toggle source

Review current revision of an article (requires FlaggedRevisions extension, see www.mediawiki.org/wiki/Extension:FlaggedRevs)

title

Title of article to review

flags

Hash of flags and values to set, eg. { 'accuracy' => '1', 'depth' => '2' }

comment

Comment to add to review (optional)

options

Hash of additional options

    # File lib/media_wiki/gateway/pages.rb
373 def review(title, flags, comment = 'Reviewed by MediaWiki::Gateway', options = {})
374   raise APIError.new('missingtitle', "Article #{title} not found") unless revid = revision(title)
375 
376   form_data = options.merge(
377     'action'  => 'review',
378     'revid'   => revid,
379     'token'   => get_token('edit', title),
380     'comment' => comment
381   )
382 
383   flags.each { |k, v| form_data["flag_#{k}"] = v }
384 
385   send_request(form_data)
386 end
revision(page_title, options = {}) click to toggle source

Fetch latest revision ID of a MediaWiki page. Does not follow redirects.

page_title

Page title to fetch

options

Hash of additional options

Returns revision ID as a string, nil if the page does not exist.

   # File lib/media_wiki/gateway/pages.rb
30 def revision(page_title, options = {})
31   page = send_request(options.merge(
32     'action'  => 'query',
33     'prop'    => 'revisions',
34     'rvprop'  => 'ids',
35     'rvlimit' => 1,
36     'titles'  => page_title
37   )).elements['query/pages/page']
38 
39   page.elements['revisions/rev'].attributes['revid'] if valid_page?(page)
40 end
undelete(title, options = {}) click to toggle source

Undelete all revisions of one page.

title

Title of page to undelete

options

Hash of additional options

Returns number of revisions undeleted, or zero if nothing to undelete

    # File lib/media_wiki/gateway/pages.rb
238 def undelete(title, options = {})
239   if token = get_undelete_token(title)
240     send_request(options.merge(
241       'action' => 'undelete',
242       'title'  => title,
243       'token'  => token
244     )).elements['undelete'].attributes['revisions'].to_i
245   else
246     0 # No revisions to undelete
247   end
248 end

Private Instance Methods

get_undelete_token(page_titles) click to toggle source
    # File lib/media_wiki/gateway/pages.rb
390 def get_undelete_token(page_titles)
391   res = send_request(
392     'action' => 'query',
393     'list'   => 'deletedrevs',
394     'prop'   => 'info',
395     'drprop' => 'token',
396     'titles' => page_titles
397   )
398 
399   if res.elements['query/deletedrevs/page']
400     unless token = res.elements['query/deletedrevs/page'].attributes['token']
401       raise Unauthorized.new("User is not permitted to perform this operation: #{type}")
402     end
403 
404     token
405   end
406 end