Falcon: Difference between revisions

This article is a stub. You can help the IndieWeb wiki by expanding it.

Falcon is a personal publishing (tweeting, blogging, realtime syndicating) web application. There is an instance of Falcon running at tantek.com and serving/syndicating blog and tweet content.

Attendees that are using it on their own site:

• Tantek Çelik (tantek.com, author (Falcon), actively developing and sharing portions as open source in http://cassisproject.com)
• ...

Disclaimer

Note: this documentation is purely for informational purposes.

There are many aspects of this design that are not optimal and that I'm working on improving. However I figured it was still worth documenting it to capture it.

If some of this helps you with designing your own indieweb implementation, great. If something doesn't make sense, ask, as there's a good chance it's something that I should fix in the design.

Thanks, - Tantek 19:37, 23 March 2013 (PDT)

Post Types

Falcon supports the following kinds of posts

• notes - with
  • white-space (serial space characters, line-breaks, blank lines)
  • auto-linking of URLs, @-names to Twitter
  • auto-embedding of JPG/PNG/GIF/MP4/MOV/OGV and Youtube/Vimeo URLs
  • POSSE to Twitter of up to 120 chars with permashortid of original post, or first 112-115 chars with ellipsing/truncating and permashortlink to original post. (assuming 6 char personal short domain, e.g. ttk.me)
• articles - blog posts
• reply notes - similar to notes, but for replying to tweets, commenting on other posts
  • current limitation: only replies to tweets (Tweet permalink URLs) are currently supported. I've wanted to POSSE my @-replies to Twitter and have them thread properly on Twitter for a while, so even just implementing this helps me interact with friends who use Twitter instead of their own site (most people).

Note: auto-linking and auto-embedding is all accomplished with the open source CASSIS auto_link function.

Feeds

Falcon supports:

• Atom with ActivityStreams object type annotations
• PuSH notifications when posts are published

POSSE Details

Falcon currently supports POSSEing:

• directly to Twitter - first 112-120 characters (depending on content), white-space preserved
  • standalone POSSE'd notes are then also automatically syndicated to Facebook (I (Tantek) have Twitter setup to do this)
  • reply notes are also POSSE'd as @-replies with proper threading (currently requires user input of original tweet permalink URL that is being replied to).

Working On

The next things I'm working on to add to Falcon:

• rel-syndication markup support (and minimal presentation based on syndication-link-use-cases) in posts in general (linking to Twitter POSSE copies).
  • Why?
    • Enable those who implement original-post-discovery to post replies linking directly to my post permalinks as well as (instead of only) POSSE their reply threaded to the respective POSSE tweet from me. e.g. this reply from Barnaby should be in-reply-to my original post instead of the tweet copy. Adding the rel-syndication link enables step 3 of the original post discovery algorithm: "see if it [the post permalink] links back to the POSSE'd copy with rel=syndication". Having those who reply to my posts link directly to them (rather than to tweet copies) is better indieweb behavior (enabling/encouraging peer-to-peer indie to indie links rather than indie to silo links), providing a more indieweb user experience.
    • Shortcut to implementing a full set of webactions (favorite, reply, (re)tweet) on my notes
• implementing replies details
  • in-reply-to markup (and minimal presentation) support in reply posts
    • Why? Provide readers at least a minimal reply-context of the URL I'm replying to.
  • replies to any URL
    • original-post-discovery to make it easier to link to the original post I'm replying to from my site, while still having my reply POSSE copy thread with the POSSE tweet of the original.
      • Why? So I can paste the tweet permalink of what I'm replying to in my posting UI, and have my site automatically link to the original instead (while the POSSE to Twitter copy still links to the tweet for proper POSSE threading).
    • rel-syndication discovery of POSSE tweets to support POSSE Replies to Twitter
      • Why? So if/when I do paste a link to an original indieweb post, the POSSE copy of my reply can be threaded with the automatically discovered POSSE copy of the original indieweb post that I was replying to.
  • sending webmentions for posted links
    • Why? Enable syndicating posts to IndieNews (assuming I have rel-syndication links implemented as noted above) and help demonstrate IndieNews as a proof of concept of an indieweb-friendly link aggregator.
    • in particular to links I'm replying to
      • Why?
        • To participate in federated indieweb commenting on others' sites! (this is a big milestone for any indieweb implementation)
        • To comment on IndieNews posts (assuming I have rel-in-reply-to links implemented as noted above) as a proof of concept of an indieweb-friendly comment aggregator/threader.

Beyond that, I find my prioritization changes often enough that I just keep a loose collection of thoughts/ideas/wants/brainstorms that I occasionally iterate on until something reaches the point of - hey, I could finish coding that in a day or two.

Itching

These are a collection of annoyances that have respective features / improvements. As their annoyance level bubbles to the top, they're likely to become concrete "Working On" tasks.

Reply Context

Itch: having to click through to the original and/or the Twitter conversation to get what the context of my replies are.

• Scratch: Display reply context on my replies so you don't have to look/go elsewhere for that.

Indie Checkins

Itch: really getting tired of venue griefers/abusers/overmergers on Foursquare. Overmergers: people who take two distinct venues and merge them into one because they have some mistaken idea of what a "venue" is. Overmerging ends up redirect both previous unique URLs to one of them, and it effectively destroys your history at checking into either, because after that, you don't know which it was. It's like wiki vandalism but worse because there is no history and no accountability.

• Scratch: Indieweb checkins from/on my own site, which then POSSE out to Foursquare (required for me because I'm a heavy Foursquare user and I wouldn't switch over to using my own indieweb checkins without that automatic capability. Mobile web support via Geolocation API is a must.)
• Scratch: Indieweb venues are essential to make indieweb checkins work and maintain data fidelity. ** Challenge: how to deal with POSSE'd venue references when silo venues are subject to such vandalism as noted in the itch description.

Code Files

Falcon consists of PHP code (some of which is CASSIS) to display posts and code to write/publish/syndicate posts. Falcon code consists of only three files (bolded), some additions to the root .htaccess, and the libraries cassis, relmeauth, and tmhOAuth in the following structure:

display: (live at http://tantek.com/ )

• cassis.js
• falcon.php
• .htaccess - only a section therein

write/publish/syndicate: (live at http://tantek.com/falcon/ )

• cassis.js
• index.php
• falconpost.php
• lib - external libraries
  • relmeauth
    • cassis.js
    • tmhOAuth

Note: as I cleanup, refine, and rewrite useful functions in Falcon in CASSIS, I've been open sourcing them in cassis.js. The following building block functions have been incorporated into other projects:

• ellipsize_to_word() - particularly useful for POSSEing out to Twitter
• auto_link() - better plain text autolinker (and embedder) than Twitter, Facebook, and G+.

- Tantek

Templates

Falcon currently only uses templates for the home page and feed. The rest of the output markup is hardcoded in falcon.php (Note: that's not good design, all output markup should be in template files. There should be no markup in the implementation code itself.).

falcon.php looks in the same directory for:

• index.html - to construct a home page with the most recent N (default: 20) posts.
  • .stream - the most recent posts are placed into an ordered list element (<ol class="hfeed">) which is then appended as the last child of the first element with class name of "stream" in the index.html template.
• updates.atom - to construct a home feed with the most recent N (default: 20) posts.
  • feed "meta" elements as well as a series of <entry> elements representing the most recent posts are appended as the last child(ren) of the last element of the template (which happens to be the <feed> element - not a very flexible design - then again, neither is Atom itself :P ).

Storage format

When displaying the most recent N posts, Falcon looks for YYYY/B.html files in the current directory (YYYY being the current year and B being the current bim) and earlier files as necessary to retrieve N posts or until a previous storage file is not found, whichever comes first.

When displaying a post permalink or archive for a particular year, bim, month, or day, Falcon computes the paths to the necessary file(s) according to year and bim and reads them.

Each bim storage file is treated as XML-Valid HTML5 hAtom and XPath is used to retrieve all .hentry elements in document order.

For each such hentry, the first (in document order) instance of each of the following is retrieved (also using XPath) from the hentry's descendants:

• .published - element parsed per the Value Class Pattern: Date and time values
• .entry-title - element parsed for both plain text and nested markup
• .entry-content - element parsed for both plain text and nested markup
• .using - element parsed for plain text
• [rel~=bookmark] - element parsed for its href attribute
• id - the id attribute of the hentry element itself is also retrieved as plain text

All "parsed for plain text" instances trim leading/trailing whitespace but preserve all other whitespace both for note permalink presentation, and for POSSEing notes to Twitter.

Every time an "hentry" is published & syndicated to a 3rd party service (POSSE style of course), falconpost.php appends a child element to the end of the "hentry" with:

• class="url u-syndication"
• rel="syndication"
• href={absolute URL to syndicated copy on another service}
• innertext - perhaps name of service and service-specific unique post identifier

e.g.:

<a rel="syndication" class="url u-syndication" href="http://twitter.com/t/status/314548524266172416">Twitter post 314548524266172416</a>

This syndication reference is also read by falconpost.php to see which entries have been syndicated to which service(s) (only Twitter is supported currently) when determining which entry to syndicate to which service next.

In addition, falconpost.php stores in-reply-to information for reply notes by appending a child element to the end of the "hentry" with:

• class="u-in-reply-to"
• rel="in-reply-to"
• href={absolute URL to original post being replied to}
• innertext - "In reply to: " and perhaps name of service and service-specific unique post identifier

e.g.:

<a rel="in-reply-to" class="in-reply-to" href="http://twitter.com/_/status/330099833383833601">In reply to: 330099833383833601</a>

See also

• Whistle
• projects