Button Button

Sputnik requests identify a node and a command to be sent by the node. The node responds to the command by executing an action. The mapping between commands and actions is defined by the node.

Each Sputnik node can perform actions in respond to commands. (If you like, you can think of pages as "nouns" and commands as "verbs".) For instance, you can get this node to send you its RSS feed by asking for:

http://sputnik.freewisdom.org/en/Actions.rss

which consists of three parts:

http://sputnik.freewisdom.org/en/
Actions
rss

This means:

  1. Call the instance of Sputnik at "http://sputnik.freewisdom.org/en/"
  2. Tell it to get the node called "Actions"
  3. Tell it to send this node the command "rss"

If command is not specified, then it assumed to be "show". So, the following two requests are equivalent:

http://sputnik.freewisdom.org/en/Actions
http://sputnik.freewisdom.org/en/Actions.show

What commands the node can understand and how it interprets them depends on the node. Some nodes can understand commands that other nodes don't understand. For instance, the node icons/sputnik, which contains base64 encoded image, commands png. Most other nodes do not know how to respond to a "png" command. Additionally, a node may use interpret differently some of the standard actions. For instance, most nodes respond to "show" by running their content through Markdown. (This node does this.) Nodes that contain Lua code (e.g., sputnik/navigation) do not do that: they display their content as code instead.

Defining actions

Each action is a function that takes three parameters and returns content (as a string) and (optionally) a content type. (If the action does not return a content type, it's assumed to be "text/html".) It can also set some attributes of the node. The three parameters to the action function are:

  • node - the node specified by the request,
  • request - a WSAPI request table, preprocessed by Sputnik to unhash parameters,
  • sputnik - the instance of "Sputnik" that is dispatching the request.

Here is a really simple action:

actions.raw_content = function(node, request, sputnik)
   return node.content, "text/plain"
end

Or a slightly more complicated one:

actions.code = function(node, request, sputnik)
   page.inner_html = "<pre><code>" .. sputnik.escape(node.content)
      .. "</code></pre>"
   return node.wrappers.default(node, request, sputnik)
end

Actions can be provided in modules, which must all be in the "sputnik.actions" namespace for security reasons. Sputnik comes with a default set of actions, provided in the "sputnik.actions.wiki" module. It includes the following action functions among others:

  • show() - display the page as HTML, with a navigation bar, etc.
  • edit() - display the edit form for the page
  • save() - save the page (when submitted by the edit form)
  • history() - show page history
  • diff() - show a diff from an earlier version
  • show_inner() - display just the content part of HTML (no menus, etc.)
  • raw() - show the content of the page "as is" - in plain text

Mapping commands to actions

Commands can be mapped to actions in the "actions" field of the node or its Prototypes. The default mappings look as follows:

actions= [[
  show  = "wiki.show"
  show_content    = "wiki.show_content"
  history         = "wiki.history"
  edit            = "wiki.edit"
  post            = "wiki.post"
  rss             = "wiki.rss"
  diff            = "wiki.diff"
  code            = "wiki.code"
  raw             = "wiki.raw"
  raw_content     = "wiki.raw_content"
  login           = "wiki.show_login_form"
  sputnik_version = "wiki.sputnik_version"
  save            = "wiki.save"
  preview         = "wiki.preview"
  preview_content = "wiki.preview_content"
]]

Configuration pages, however, override this setting because "actions" is set as follows in @Lua_Config:

actions= [[
  show_content="wiki.show_content_as_lua_code"
]]

This means, that all nodes that inherit from @LuaConfig respond to "showcontent" by running sputnik.actions.wiki.actions.show_content_as_lua_code() instead of the regular sputnik.actions.wiki.actions.show_content().