Getting started with Manila and SOAP

Wed, Mar 14, 2001; by Jake Savin.

This page explains how to get started editing the home page of your Manila site using SOAP to make calls to Manila's RPC interface.

Any environment which supports SOAP or XML-RPC may be used to edit Manila sites. All you'll have to do is emulate the functionality of the examples on this page in your environment of choice.

Getting your site's name 

Every Manila site has a name which is unique for a given server. This is the site's "canonical name", and it's needed in order to identify the site you want to manipulate, when making most RPC calls.

Here's an example UserTalk script which asks the server to supply a site's canonical name:

local (host = "mysite.manilasites.com")
local (port = 80)
local (siteUrl = "http://mysite.manilasites.com/")

local (siteName)
local (params = {siteUrl})
siteName = soap.rpc.client ("/manila", "getSiteName", @params, host, port)

return (siteName)

The script calls a method on the server, manila.getSiteName, with a single parameter: the URL of the site as a string. The server returns the canonical name of the site.

In the call to soap.rpc.client, "/manila" is the value of the SOAPAction HTTP header, "getSiteName" is the method name, @params is the address of the parameter list for the RPC call, host is the DNS name or IP address of the server, and port is the port number to connect to for the RPC call.

Getting the home page message number 

In a Manila site, every story or home page is a message. Every message has a unique message number.

If you want to work with the home page of a Manila site, you will first need to find out which message contains the home page.

Here's an example script which gets the message number for the site's current home page:

local (host = "mysite.manilasites.com")
local (port = 80)
local (siteName = "mysite")
local (username = "jake@userland.com")
local (password = "forgetit")

local (homePageMsgNum)
local (params = {username, password, siteName})
homePageMsgNum = soap.rpc.client ("/manila/homepage", "getMsgNum", @params, host, port)

return (homePageMsgNum)

The script calls the manila.homepage.getMsgNum method, which takes three parameters: username, password and siteName. The username and password must identify a managing editor of the site, and the siteName is the canonical name of the site obtained above.

Getting the text of the home page 

Once you know the message number for the home page, you can get its contents for editing. The example above returned 1, meaning that the home page for my site is message number 1.

This example script gets a message from the server:

local (host = "mysite.manilasites.com")
local (port = 80)
local (siteName = "mysite")
local (username = "jake@userland.com")
local (password = "forgetit")
local (msgNum = 1)

local (messageStruct)
local (params = {username, password, siteName, msgNum})
messageStruct = soap.rpc.client ("/manila/message", "get", @params, host, port)

return (messageStruct)

The script calls the manila.message.get method, which takes four parameters: username, password, siteName and msgNum. As above, username and password identify a managing editor, and siteName is the canonical name of the site. The msgNum is a number -- the message number for the home page, which was returned by the previous example.

The server returns a struct, which contains the text of the message, an some information about it. The important sub-elements of the returned struct are:

body -- The text of the message as a string.

bodyType -- The MIME type for the body. Possible values are text/plain for plain text, text/x-opml for an OPML document and text/x-outline-tabbed for a tab-based outline.

subject -- The subject of the message, which is the title of the home page.

(See below for more about the struct the server returns when getting a message.)

Once you have the text of the home page, you can pass it along to your text editor of choice.

Setting the text on the home page 

Once you've edited your home page content in your text editor, you'll want to save it back to the site. Here's an example script which does just that:

local (host = "mysite.manilasites.com")
local (port = 80)
local (siteName = "mysite")
local (username = "jake@userland.com")
local (password = "forgetit")
local (msgNum = 1)
local (subject = "My Home Page")
local (body = "Here's some text on my home page which was put here using SOAP!")
local (bodyType = "text/plain")

local (params = {username, password, siteName, msgNum, subject, body, bodyType, 0, 0})
soap.rpc.client ("/manila/message", "set", @params, host, port)

The script calls manila.message.set to set the contents of your home page message. In fact, this method is also used to set the contents of any message or story in a Manila site.

Here are the parameters:

username and password -- Identify a managing editor of the site.

siteName -- The canonical name of the site.

msgNum -- The message number for the message to set, which in this case is the home page.

subject -- The subject of the message (title of the home page).

body -- The text of the message, as a string, tabbed outline, or OPML document, in this case a string.

bodyType -- The MIME type of the body, in this case text/plain.

The last two parameters, windowInfoTable and rendererInfoTable are used to specify window size and position so that an editor can restore the window when the message is edited, and rendering information so the server will know how to display the message, respectively.

The windowInfoTable is optional, which is why we pass in 0.

rendererInfoTable is used then the bodyType is text/x-opml, so it's not necessary to specify in this example.

Like manila.message.get, manila.message.set returns a struct with information about the message, but in this example, we can ignore the server's response.

Manila and XML-RPC 

The Manila RPC interface is supported for both SOAP and XML-RPC. All of the methods you can call with SOAP can also be called using XML-RPC. In UserTalk, the code is nearly identical. The first example script above could be changed so that it uses XML-RPC, by modifying a single line:

Change:

siteName = soap.rpc.client ("/manila", "getSiteName", @params, host, port)

To:

siteName = betty.rpc.client (host, port, "manila.getSiteName", @params, rpcPath:"/RPC2")

This is one of the beautiful things about the Manila RPC interface.

Now you have everything you need to implement your own home page editor for Manila sites in any environment which supports SOAP or XML-RPC.

Other useful Manila methods 

There are other calls you can make which are useful for manipulating your site's home page. Here's a list:

manila.homepage.addToHomePage -- Adds a bit of text to the top of the current home page.

manila.homepage.flip -- Creates a new, empty message, and sets the current home page to the new message.

manila.homepage.setMsgNum -- Sets the current home page to a specified message number.

See the Manila RPC spec for implementation details for these and other Manila methods.

What's in a messageStruct 

For the adventuresome, there's a lot of information in the struct the server returns when you get a message. Here's the full list of the server returns:

alsoListedIn -- An array of categories that the message is listed in.

body -- The body of the message.

bodyType -- The MIME type for body, text/plain, text/x-opml or text/x-outline-tabbed

ctReads -- The number of times the message has been read.

flNewPostNotificationSent -- A boolean specifying whether the editors of the site have been sent an email notifying them that the message was posted. If this value is not present, it's assumed to be false.

flServerAcceptsOpml -- A boolean specifying whether text/x-opml is a valid bodyType for this server. If this value is not present, it's assumed to be false.

inResponseTo -- A number specifying which message this message is a response to. If the value is 0, then this message is the top message in a thread.

lastUpdate -- A date specifying when the message was last updated. If not present, its value is assumed to be the value of postTime. (See below.)

member -- The email address of the member who created the message.

memberName -- The name of the member who created the message. This value may or may not be present.

msgnum -- The message number for the message.

postTime -- The date/time that the message was posted.

renderInfo -- A struct containing flRenderOnEntry, a boolean, and name, a string. If bodyType is text/x-opml, then flRenderOnEntry will be true, and name will be pikeRenderer. This value may or may not be present.

responses -- An array of zero or more numbers, specifying message numbers for all responses to this message.

subject -- The subject of the message. This is also the title of a home page or story.

url -- The URL of the message.

windowInfo -- A struct containing expansionState, an array of line numbers for lines in an outline which are expanded, scrollLine, the number corresponding to the line the cursor is currently on, top, thevertical position of the top of the window, left, the horizontal position of the left edge of the window, height, the height of the window, and width, the width of the window. This value may or may not be present.