Yesterday I wrote a post about the gateway that connects Fargo with WordPress.

In that post, I suggested that it is possible to replace that gateway, which does not handle unicode characters, with one that does. It is possible, and for a reasonably skilled server programmer, not even very much work. In this post I want to outline the problem, at a technical level.

The gateway

• It sits between Fargo and WordPress.

• Fargo is a JavaScript app running in the browser.

• We call the gateway with the jQuery routine $.ajax.

• In our gateway, we call WordPress through the MetaWeblog API, though a new gateway could use a different API, as long as it maintains the same interface to Fargo.

The parameters we send with the request are

• postTitle: the title of the post.

• postBody: the body of the post.

• idPost: the ID of the post, 0 if it's a new post.

• weblogUrl: the URL of the WordPress blog.

• blogUsername: the user's username.

• blogPassword: the user's password.

What the server does

• First, it gets the calling conventions for the blog using Really Simple Discovery to turn weblogUrl into an API address and a blog ID. It caches this result so subsequent calls won't have to go through the full RSD process.

• Then it makes a MetaWeblog API call to the WordPress server. Which call it makes depends on whether idPost is zero or non-zero. If it's non-zero it makes a metaWeblog.editPost call, if it's 0, it makes a metaWeblog.newPost call.

What the server returns

• In all cases it returns a JSONP call, to a routine called getData, with a single param, a JSON struct, that contains several fields.

  • link: points to the blog post.

  • idpost: the WordPress ID for the post, used in subsequent calls to identify the post.

  • error: its presence indicates that the call did not work. Its value is an error string that can be displayed for the user explaining the error.

• The content type of the response is application/json.

Access-Control-Allow-Origin header

• Very important: the gateway must set the Access-Control-Allow-Origin header to fargo.io, so the browser will let Fargo call your service.

Source code

• I'll provide source code for both the $.ajax call from Fargo and the gateway (written in UserTalk running in Frontier) as example-ware.

Business

• I wrote the gateway in January in a couple of days. It took that long because I was unfamiliar with the way the $.ajax process works. It might still take a couple of days to get it up and running and tested and well-enough debugged so users can depend on it. It's the kind of code that takes two or three sessions to complete.

• To deploy, it will have to be on a publicly-accessible server. On Amazon or Rackspace that server would cost less than $100 a month to run.

• One server could easily support the Fargo community, even with a fair amount of growth. WordPress is at this time a fairly small application for Fargo. Of course if it worked better it might be a larger application.

• Doc Searls contacted me today, a Fargo user, who runs a WordPress blog, and he has an interest in making this work, and has offered (I think) to help coordinate.

• I would love to see this as a community development thing. I will show people how to configure Fargo to talk with a different server. We can make it a preference, to make it as easy as possible.

New link for the worknotes site

• There's a link to the Worknotes site in the Docs menu.

• Since the site has moved, the menu item now links to the new location.

Feed for worknotes

• It's also worth mentioning that because we're using Fargo to manage the worknotes, there's now a feed that you can subscribe to:

  • http://docs.smallpict.com/rss.xml

• And because this all is in one place now we can have technotes too, and they will show up in the feed as well.

Fix for the Home icon

• Previously, the home icon (in the left margin) took you to the web view of the named outline. For example, if your outline was named george, the home button would take you to george.smallpict.com. This is usually the right answer.

• However, if you've used the domain attribute to map to a different domain, the web view of the named outline is probably not where you want to go, if your cursor is nested inside the headline with the domain attribute.

• So starting in 0.99, we first check to see if you're inside a domain attributed headline, and if so, we go there.

New verb: op.getCursorUrl

• As its name implies, it returns the URL for the cursor, if it has one, otherwise it returns undefined.

• If the headline is within a page, we return the URL for the page, by shooting out to the summit looking for a node with a type attribute. When we find one, we return its URL. So it's not a precise verb.

• It's good for building redirects, static indices, stuff like that.

This has come up on the smallpicture-user mail list.

I can give you all the info you need on this one, but you're probably not going to like it. ;-(

In order for Fargo to communicate with WordPress, we have to go through a gateway.

The software on this gateway is old. It does not understand unicode. So as long as you stick to 8-bit characters, you're cool. But when you use characters outside the 8-bit set, you can be pretty sure it will get mangled in transit.

I can't do anything about this. However if someone else wants to create a gateway without this problem, I can make it so that Fargo can talk with that gateway. The person doing this would have to be a reasonably skilled server developer, and have a server to run the gateway on.

If someone is interested in doing this they should contact me off-list, or if you prefer, post a comment here.

I had been tweaking the index template on dave.smallpict.com.

I posted an RFC on the smallpicture-web list, but there were no comments.

So I'm going ahead and making the switch. If all goes well the home page of this site will now be using the new index template.

I'm going to start publishing worknotes over here. Will take care of bringing across the existing worknotes shortly.

Update: The worknotes have been brought across.

This is going to be a combination of a blog and a documentation site.

If everything works the way I hope it will.

If not, I'm going to have some serious thinking to do!

Shift-click on Eye icon

• If you want to get the URL of a page without having to go to the page, shift-click on the Eye icon in the left margin. A dialog will appear that contains the URL. You can copy it to the clipboard there. Saves a couple of steps.

New img attribute

• You could, before 0.98, include an image in a Fargo blog post by adding HTML to the text of the post.

• Now it's a bit simpler.

  • 1. Get the URL of your image on the clipboard. If you don't have one handy, use this one.
  • 1. In Fargo, put the bar cursor on the headline that you want to attach the image to. The image will appear in the right margin of the post at the start of this headline.

  • Note: The img attribute must appear on a line within the post, not on the title headline of the post.

  • 1. Click on the suitcase icon in the left margin.
  • 1. Add a new attribute by clicking the + button. It's name is img, the value is the URL you have on the clipboard.
  • 1. Click OK.

• When you view the outline in a web page, the image will appear in the right margin. It will also appear in the RSS feed.

New settings, RSS features

• There are a couple of new entries on the You panel in the Fargo Settings dialog, for your Twitter and Facebook usernames.

• If you enter values for these entries, we will generate new elements in your RSS feeds that contain this information.

• This is an experiment. We're adding these features in the hope that other developers will use the information to add features to their products. Then we'll add some more stuff, and others will too, and hopefully RSS will improve and become more useful. It's been quite a while since people worked together on improving RSS.

Viewing commented pages

• When you click the eye icon to view a page, we now check to see if it's commented. If it is, instead of taking you to the page, which will show up 404 not found, we ask if you'd like to uncomment it. Then you can click the eye icon again, after waiting a few seconds for the outline to save, and for the CMS to notice the change.

Creating commented headlines with + icon

• In previous versions the headlines would be commented, but they weren't visibly commented. Now they are.

Perspective

• As we're getting close to 1.0, I wanted to offer a few observations on where we're at and how it's going.

Home icon in left sidebar

• Suppose you're editing a named outline and you want to quickly view the home page of the site. There's actually no UI for in prior to 0.97. You have to type the URL in the browser's address bar. This won't do!

• Now the Home icon shows up in the left sidebar whenever the eye icon does.

• Click on it to view the home page of the side in a new tab/window.

New command in Outliner menu

• A new Outliner menu command toggles between Render and Non-render mode. The single keystroke is Cmd-`.

• In render mode HTML entities are seen as they would be seen in a web page rendering of the content. This is possible because Fargo runs in the browser, which of course, naturally renders things as HTML.

• In non-render mode, the entities appear unrendered. So in image would show up in non-render mode as an <img> tag.

• This command worked in earlier versions of Fargo and Little Outliner, but it wasn't present in a menu, so was harder to discover.

• A screen shot of an outline in render mode, and a screen shot of the same outline in non-render mode.

File menu changes

• Removed two commands from the File menu, View in Reader and Save as Markdown.

• Added these back as new scripting verbs, file.viewCurrentFileInReader () and file.saveCurrentFileAsMarkdown ().

• If you were depending on these commands, you can add them back menubar.opml.

• The reason for removing them is that there are now better ways to read content created in Fargo, using the web content management system. Having these commands in the menus were confusing for some users.

• See: Intro to Fargo Scripting.

In previous versions, if you had a page with type or method equal to markdown, it would render fine on the website, but its markdown nature would be ignored by the feed generator. That's now fixed.

This post, as an example, has a method attribute of markdown, and it should appear with proper markup in the feed.

Before this release, the + icon required that the calendar be at the top level of the outline. Now, the calendar can be anywhere in the outline.

Not a whole lot more to say about it.

One small feature, a nice thing to have, not crucial.

If you put an insertedNodeType attribute on your calendar, then when you click the + in Fargo, that type will override the type you set in the Insert settings panel.

You could also put the attribute on a month or a day. But it probably makes the most sense to put it on the year. You will have to remember to copy it to 2014 at the beginning of the next year.

This allows you to maintain several blogs which may not want to use the same type for posts.

Screen shot.

Rearranged the right sidebar.

Removed links to docs that were already in the Docs menu.

Moved the Save button up, and the Message of the Day down.

Fargo will work better on shorter screens as a result.

The equivalent of draft mode

• New setting in the Insert panel, allows you to tell Fargo to create new items with the + icon as comments. Comments will not be rendered by Trex, and will not appear in your RSS feed. This is useful if you're creating posts and don't want them to be viewed until they're finished.

• The workflow:

  • 1. Click + to create a new post.
  • 1. Edit your post until you're happy with it.
  • 1. Put the cursor on the top head in the post.
  • 1. Choose Toggle Comment in the Outline menu.

  • When the outline is next saved the new item will then appear on the site, and will be included in the RSS feed.

• Screen shot.

Redundant setting

• Removed the Autosave pref from the Advanced panel in Settings. There is a panel just for Autosave, so the setting was redundant.

New #directive

• For some of my posts I wanted the comments to be visible when the page is displayed, not hidden.

• So there's a new attribute, flCommentsVisible that says whether the comments are initially visible.

• Here's a post that illustrates.

• You can set it true after the fact, when a post attracts a lot of comments that you want people to see.

• Note: It's only effective if flCommentsHidable is true.

A curiosity

• Whole version numbers like 1.0 mean nothing at Small Picture. Every time there's a new release we bump the version by 1/100th.

This feature is described in the Blogging howto.

Switched from Font Awesome 3.1 to 3.2.

I took notes on the work on my Fargo blog.