Extension:StructuredDiscussions/API
Most Flow API read and write interactions are submodules of action=flow
. Flow also implements a query property flowinfo
and a parsing utility module flow-parsoid-utils
.
Detection
editflowinfo | |
---|---|
This module cannot be used as a generator. | |
Prefix | fli |
Required rights | none |
Post only? | No |
Generated help | Current |
prop=flowinfo
(details below) is one way to check if Flow is enabled on the specified pages.
You can alternatively use prop=info
to retrieve page info including content model. The content model will be 'flow-board' if it's enabled. Compare Special:ApiSandbox#action=query&titles=Project:Village+pump&prop=info and Special:ApiSandbox#Extension:StructuredDiscussions/API&prop=info.
In client-side JavaScript (for gadgets and user scripts), call mw.config.get( 'wgPageContentModel' )
.
The following documentation is the output of Special: |
prop=flowinfo (fli)
- This module is deprecated.
- This module requires read rights.
- Source: Flow
- License: GPL-2.0-or-later
Get basic Structured Discussions information about a page.
- Fetch Structured Discussions information about Talk:Sandbox, Main Page, and Talk:Structured Discussions
- api.php?action=query&prop=flowinfo&titles=Talk:Sandbox|Main_Page|Talk:Flow [open in sandbox]
action=flow
editflow | |
---|---|
This module cannot be used as a generator. | |
Prefix | none |
Required rights | none |
Post only? | No |
Generated help | Current |
The following documentation is the output of Special: |
action=flow
- This module requires read rights.
- Source: Flow
- License: GPL-2.0-or-later
Allows actions to be taken on Structured Discussions pages.
- submodule
The Structured Discussions submodule to invoke.
- edit-header
- Edits a board description.
- edit-post
- Edits a post's content.
- edit-title
- Edits a topic's title.
- edit-topic-summary
- Edits a topic summary's content.
- lock-topic
- Lock or unlock a Structured Discussions topic.
- moderate-post
- Moderates a Structured Discussions post.
- moderate-topic
- Moderates a Structured Discussions topic.
- new-topic
- Creates a new Structured Discussions topic on the given workflow.
- reply
- Replies to a post.
- undo-edit-header
- Retrieve information necessary to undo description edits.
- undo-edit-post
- Retrieve information necessary to undo post edit.
- undo-edit-topic-summary
- Retrieve information necessary to undo topic summary edits.
- view-header
- View a board description.
- view-post
- View a post.
- view-post-history
- View the revision history of a post.
- view-topic
- View a topic.
- view-topic-history
- View the revision history of a topic.
- view-topic-summary
- View a topic summary.
- view-topiclist
- View a list of topics.
- close-open-topic
- Deprecated. Deprecated in favor of action=flow&submodule=lock-topic.
- This parameter is required.
- One of the following values: edit-header, edit-post, edit-title, edit-topic-summary, lock-topic, moderate-post, moderate-topic, new-topic, reply, undo-edit-header, undo-edit-post, undo-edit-topic-summary, view-header, view-post-history, view-post, view-topic-history, view-topic-summary, view-topic, view-topiclist, close-open-topic
- page
The page to take the action on.
- Default: Topic:Flow-enabled_page
- token
A token retrieved from action=query&meta=tokens
- Default: (empty)
(Since this edit operation has to be an HTTP POST, the link in the generated example above won't work.)
Replying
editIn a reply you're replying to a particular post in a workflow (a topic). Flow objects are identified by UUIDs see Flow/Architecture.
To reply to a topic
- you'll need a token. Flow recently switched to using the regular 'edit' token for most operations, so you can use
mw.api.postWithEditToken
to get the editing token if it hasn't been cached yet in the session. it's cached. - Issue a
flow
API request withflowaction=reply
, identifying the topic workflow. The parameters for a reply include the topic and the post.
action=flow submodule=reply format=json repreplyTo=050fed5dc6bd5085237590b11c2fa805 repcontent=My reply, with ''wikitext''. render=true token=43a71deb105e7c0be7e8eeab4bdff4f7+\ workflow=050f698e3f6e5624fa1590b11c27932f
- Set
render=true
if you want the server to respond with the "fully-decorated" HTML to interact with the new post (preview buttons, actions, etc.). - UUID format will soon change to be more compact, using 88-bit represented as alphadecimal.
- Obviously you get the topic and post to respond by making API queries, rather than hardcoding these numbers.
Note that a wiki may store Flow content with $wgFlowContentFormat
'html' or 'wikitext', but in any edit submission you must submit wikitext.
If successful, the server responds with the post-id
of the new post, and the HTML to insert into the DOM.
Note this API request doesn't name the page on which the topic appears. Users interact with topics on a Flow board with a wiki page name, but a topic might (eventually) appear on multiple pages, e.g. a user's "subscription feed".
On WMF wikis, Flow stores post content as HTML with embedded Parsoid markup so that something resembling the original wikitext can be reconstituted for editing. This will not be the case on all wikis, others might store as wikitext.
Block requests
editWhen you make a "Block" API request such as &submodule=new-topic
, the API normally returns a flow.new-topic.result.topiclist
containing updated information about the top 10 topics on the board, including their HTML. This allows the Flow board to redisplay the board contents, but it can be a lot of data.
If you are just trying to add a topic and you're not interested in the board contents, you should pass the flag ntmetadataonly=true
(gerrit:180588)
Flow returns the metadata in a top-level flow.newtopic.committed
key in the API response. For consistency the information about the new content is returned as topic-page, topic-id, topic-revision-id, post-id, header-post-id (but see phab:T84954), etc.
Editing the board header
editIf you want to update the Flow board header, it's similar
- make a GET request
action=flow, submodule=view-header, vhformat=wikitext
to get the current contents. This will return aflow.view-header.result.header.revision
including a UUID of the most recent version of the header inrevisionId
, and its contents incontent.content
. - make a POST request,
action=flow, submodule=edit-header
. Setehprev_revision
to the revision returned by the GET request and setehcontent
to your updated wikitext.
The update may fail with error.code = 'prev_revision'
if someone else updated this board's header between the two requests; if so the return has a prev_revision.revision_id
giving the new latest revision, so you can retry with that. However, you should avoid clobbering the previous editors' work (e.g. by presenting an edit conflict form, or re-running the algorithm if a bot is making the requests, etc.).
Posting a new topic from on-wiki JavaScript
editIf an on-wiki user script or gadget needs to be post a new topic, the best way is to use MessagePoster. The advantage is that you don't need to know whether the talk pages uses old-style talk pages or Flow. It will work either way (LiquidThreads is not supported).
mw.loader.using( [ 'mediawiki.Title', 'mediawiki.messagePoster' ], function () {
var title = new mw.Title( 'Talk:MyTalkPage' );
var posterPromise = mw.messagePoster.factory.create( title );
posterPromise.done( function ( poster ) {
poster.post( 'This is the topic title', 'This is the body of a message posted with MessagePoster' );
} );
} );
action=flow-parsoid-utils
editflow-parsoid-utils | |
---|---|
This module cannot be used as a generator. | |
Prefix | none |
Required rights | none |
Post only? | No |
Generated help | Current |
The following documentation is the output of Special: |
action=flow-parsoid-utils
- This module requires read rights.
- Source: Flow
- License: GPL-2.0-or-later
Convert text between wikitext and HTML.
- from
Format to convert content from.
- This parameter is required.
- One of the following values: html, wikitext
- to
Format to convert content to.
- This parameter is required.
- One of the following values: html, wikitext
- content
Content to be converted.
- This parameter is required.
- title
Title of the page. Cannot be used together with pageid.
- pageid
ID of the page. Cannot be used together with title.
- Type: integer
- Convert wikitext '''lorem''' ''blah'' to HTML
- api.php?action=flow-parsoid-utils&from=wikitext&to=html&content='''lorem'''+''blah''&title=Main_Page [open in sandbox]