You're viewing old version number 52. - Current version

24 min

Junco User Documentation

Junco was designed to support multiple users who create blog posts, microblog posts, replies, and follow users and tags.

But in the example usage below, the app is used as a one-person personal publishing site. The documentation, however, will explain usage as if multiple people used the app.

Example usage: http://jothut.com

Account Creation

A new user enters a username and a valid email address. The system sends the user an email with an auto-generated password and a link to activate the account. After the account is activated, the user can login.

Logging In

To log into the app, a user provides an email address and password. The username is not used for logging in. The username is used for display within the app. Posts are assigned to the username.

Changing Password and Email

After logging in, the user can click on his or her username and follow the link and form fields to change the password and email.

Requirements for passwords created by the user:

  • must be least 8 chars long.
  • max char length is 30.
  • must contain at least 4 alpha chars.
  • must contain at least 2 numeric chars.
  • must contain at least 2 chars from the following list: !@$%^&*
  • the alphas, digits, and jibberish chars do not have to be unique, so a password can contain two exclamation marks, which satisfies the jibberish requirement.

Generate New Password

On the login page, a user can request the app to generate a new password for the username and email address provided.

Editing the Profile Page

Users can personalize their profile page by adding links, plain text, or Textile markup to create HTML. The profile page data entry box supports template includes and the double-bracket wiki link feature.

Search

The search applies to microblog posts, blog posts, replies, webmentions, all content posted, except blog posts that have had the private=yes command applied.

In the text input field box for searching, enter one of the following:

  • the search term(s)
  • the search terms separated by AND
  • the terms separated by OR

The AND-OR operators need to be typed in uppercase.

On a search results page, a permalink for the search is displayed with a pound sign link, and an RSS link also exists for the search results. The RSS feed contains the 20 most recently created/updated blog and microblog posts.

This simple search may need enhanced because it will return results that contain part of the search term. For example, a search on the word "junco" will also return results that contain the phrase "juncocode".

Default search is done on the exact phrase of words typed into the search text field box.

Separate words with OR to match on any word, which means the search is a match if at least one word in the list is found in the article.

Use AND to match on all words, which means all of the words must appear somewhere within the article.

Your search terms can be in upper or lower case, but the OR and AND must be in caps.

Example search inputs:

  • exact phrase: Lake Erie
  • match any word: Toledo OR Monroe OR Bowling Green
  • match all words: swamp AND river AND lake

Currently, the AND and OR commands cannot be combined.

You can also use the URL to conduct a search.

Example:

/search/art

The AND and OR commands be used in the URL too by connecting words with the plus sign:

/search/toledo+AND+monroe

Hashtags

Microblog posts (notes) and blog posts (articles) are limited to a max of eight hashtags.

Hashtag format consists of meaningful, categorical, alphanumeric text preceded by the pound sign.

Hashtags are used to organize and identify content. Tags help with searching.

I like to start with the general and move to the specific when including tags.

Examples (with the pound signs excluded):

  • nature - insects - butterflies
  • sports - football - nfl - browns
  • media - design - mobile - app

A "tags" link exists to show all microblog and blog postings with tags. The tags can be displayed by name, count, tag cloud, and the top 30 tags.

A max of eight tags are permitted per post.

An RSS feed can be obtained for each tag. The feed shows the 20 most recently created/updated posts.

Displaying posts that contain a particular hashtag is really a special form of the search function.

The AND-OR operators can be used with searching or displaying a stream of tagged posts.

Example URL:

The above URL will return all postings (microblog and blog) that contain the hashtags "mobile" and "design."

Microblog Posts or Notes

These are short posts with a limit of 300 characters. They are entered in the small textarea box, located on the homepage.

Titles are not entered.

No preview, just a post button.

The only formatting includes:

  • Raw URLs are converted into clickable links.
  • Hashtags converted into clickable search links.
  • /1234/ means linking to another microblog post that has ID number 1234.

Microblog posts cannot be edited.

But microblog posts can be deleted from the home page stream by clicking the [delete] link. The post is not removed from the stream. A deleted post can only be viewed on the home page stream by the logged-in owner. The deleted post will appear with very small text with a light yellow background. The deleted post can be added to public viewing by clicking the [undelete] link.

The RSS stream for a user's microblog posts can be accessed on the user's profile page.

Blog Posts or Articles

These can be short or very long.

Posts can be entered in a medium-sized textarea box, or the enhanced 'editor' can be used.

Blog posts can be previewed before being saved.

Blog posts can be edited.

Versions

Old versions are preserved. To revert back to an old version, the user edits the old post and saves the post.

Differences

Differences can be run on two versions, showing changed, additions, and deletions.

Titles

No separate input text field exists for the title. The first line in the blog post is used as the title. If the line is long, then the first 150 characters will be the title.

If the title contains a colon punctuation mark, then the text preceding the punctuation mark must equal the username of the user creating the post. This namespace convention allows users to create common titles with their username in the title.

If a blog post is created with a title that matches an existing post that was created by any user, then an error will be displayed.

Markup Support

Blog posts support Textile, Markdown, and MultiMarkdown formatting. Textile is the default markup.

Many HTML tags are also supported.

Blog Post Types

Blog posts can be set to private where only the logged-in owner can view the post. It will not appear within the logged-in owner's home page stream. The owner can access private posts through the user's profile page.

Blog posts can be set to draft where they are still publicly displayed, but draft posts do not appear on the home page stream. Draft posts could be found through searching. The owner can view a stream of draft posts via the profile page. Draft posts are automatically created when the double-bracket wiki markup is used, and the post identified by the title contained within the double brackets does not exit.

Table of Contents

If header lines are used within a blog post, then by default a table of contents is created and displayed at the upper right area of the page. The table of contents display, however, can be disabled.

By default, a table of contents for the article will be created and included into the formatted content stored in the database. The TOC will be created based upon the html heading commands: h1, h2, h3, h4, h5, h6.

Viewing Blog Source

Users can view the markup source for a blog post.

Related Articles

Based upon the hastags used within a blog post, a list of "Related articles" is displayed at the bottom of the blog post. This list is generated when two or more hashtags match other blog posts. Five related articles are displayed. If more than five exist, a "more" link is displayed that will take a user to the page that shows all the related articles. This feature not apply to nor include microblog/notes postings.

Blog Posts Stream

When showing a stream that includes blog postings, only the first 250 characters of each blog post is displayed within the stream. If the post is longer than 250 characters, a "more" link is displayed.

Blog posts can be deleted from the home page stream by clicking the [delete] link. The post is not removed from the stream. A deleted post can only be viewed on the home page stream by the logged-in owner. The deleted post will appear with very small text with a light yellow background. The deleted post can be added to public viewing by clicking the [undelete] link.

RSS

The RSS stream for a user's blog posts can be accessed on the user's profile page. The feed contains the 20 most recently created/updated blog postings (articles).

Archives

The "archives" page only applies to blog posts.

Special Blog Formatting Tag

The blog_[username] hashtag is used to create a specially formatted stream of blog postings. Only the author's username can follow the "blog_" text when using this hashtag. After clicking on this special tag, the formatted stream will look more like a traditional blog home page.

It's recommended to use the "more." command when applying the "blog_" hashtag. The text preceding the "more." command will appear on the specially formatted blog home page stream. On the blog home page, the "more" link will be displayed to indicate more text exist. If the "blog_" tag is applied to a post, and the "more." command is not used, then the entire blog post will be displayed on the specially formatted blog home page stream, which may be desired for small posts.

The home page stream for this special tag displays posts by creation date. Recently updated blog posts do not appear at the top of the stream, which is what happens on the normal stream display for blog/article postings.

This special tag also includes an RSS feed that displays the 20 most recently created blog postings. Again, recently updated blog posts do not appear at the top of the RSS feed.

The special "blog_" tag attempts to preserve traditional blog functionality.

Image Headers

These commands apply to blog posts that use the special "blog_" tag.

imageheader=URL to image

or

largeimageheader=URL to image

The large image is displayed when viewing the blog post.

These large images, however, are not displayed when viewing the stream of specially formatted blog posts.

Redirecting

A blog post can be made to redirect to another posting by using the at-sign at the beginning of a line, followed by the blog post ID number of that a user should be redirected to.

Article redirect

To redirect an article to another article, use:

@article_id

Example: @123

The at sign needs to appear at the beginning of the line of the article you don't want displayed. The article id follows the at sign. The user will be shown the article represented by the id number following the at sign.

The article containing the redirect does not need to have its contents deleted. The user will see text at the top of the page indicating the user was redirected from another page. If the user has edit privs, the user can edit the page with the redirect code, in case the redirect wants to be removed.

Power Commands

These commands typically start at the beginning of a new line. Most take either a "yes" or "no" option.

  • toc=yes|no
  • draft=yes|no
  • replies=yes|no
  • private=yes|no
  • showintro=yes|no
  • code=yes|no
  • markdown=yes|no
  • multimarkdown=yes|no
  • webmention=yes|no
  • imageheader=URL
  • largeimageheader=URL

Embedding Media

The img HTML tag is permitted.

Markdown and Textile provide commands to display an image.

These custom commands are used to display other media: #todo show example usage

  • gmap=
  • kickstarter=
  • facebook=
  • youtube=
  • vimeo=
  • gist=

Enhanced Blog Writing Area

Can type and view in split-screen or single-screen modes.

Auto-save occurs every five minutes, provided that at least one key was pressed. The "save" link can be clicked to save too.

If the "preview" link is clicked while in split-screen mode, then the preview will be displayed in split-screen mode.

If the "preview" link is clicked while typing in single-screen mode, then the preview will be displayed in single-screen mode. This preview will display at the same width as the website's width defined in the CSS file.

Click the right arrows changes the mode to single-screen. Clicking the left arrows switches to split-screen mode.

This does not contain live preview. When testing, I found live preview to be too distracting. I could see letters flashing onto the preview part of the screen out of the corner of my eye as I typed. Plus, I have added too many custom formatting options, such as custom Textile-like formatting commands, template includes, etc., that are best achieved with a round-trip to the server. Since this round-trip is plenty fast, I don't see this as a problem.

Keyboard Commands

  • ctrl+P = preview
  • ctrl+U = single-screen mode
  • ctrl+S = save

Old screen shots


split screen, typing on left and preview on right.

enhanced view 1


single screen view for typing.

enhanced view 2


single screen view for previewing.

enhanced view 3

When moving away from the enhanced writing area, you will get a pop-up message, asking if you want to leave the page. Click "confirm" or whatever the answer is to leave the page.

This confirmation pop-up will appear even after you have saved the content.

This confirmation exists because over the years, I've experienced times where I accidentally moved away from a page that I was adding content to, and when I quickly moved back, all my content was gone and not saved. So I added this pop-up to my new app as a safety feature.

This "confirm" pop-up does not function on Apple devices.

Simpler Enhanced Writing Area

It's also possible to simplify the enhanced writing area even more. These views borrow from the writing area at Github. These actions only exist as keyboard commands. When writing in this simpler, enhanced view, the above keyboard commands can be used too. And the other actions, such as autosave also works here. It's the same JavaScript editor code.

  • ctrl+J - bare display that shows only the single textarea box for writing. no border, no nav bar, no buttons, no links.
  • ctrl+H - bare display per above except textarea box is only five lines tall.
  • ctrl+D - change display from dark text on a light background to light text on a dark background.
  • ctrl+B - reverts back to the original splitscreen display with original colors, buttons, etc.

RSS Feeds

RSS feeds are available for the following streams of content:

  • blog posts
  • special blog_[username] hashtag
  • microblog posts
  • all postings combined
  • search results
  • hashtags

Feed command

use the double-curly brace feed command to display results from a RSS or atom feed within the page.

{{feed= URL followed by two right curly braces.

do above except include the "desc" attribute within the double-curly brace and after the URL to the RSS/atom feed.

the "desc" attribute should display description information if it's available within the XML file.

Follow Users

click on profile of another user. click the follow button. check own profile page for the following info: show list of users being followed click on stream of posts by followed users click on the following link in the nav bar to show stream of posts by followed users. click on the followed user's profile page and click the unfollow button. verify the unfollowing changes on own profile page and within the following link in navbar.

Follow Tags

click on a hashtag and click on the follow button. check own profile page for the following info: show list of tags being followed. click on stream of posts that contain the followed tags. click on the following link in the nav bar to show stream of posts that contain the followed tags. click on the followed tag to get a search result, and click the unfollow button. verify the unfollowing changes on own profile page and within the following link in navbar.

Backlinks

(backlinks - Backlinks - show_backlinks) create a blog post that contains a normal URL link or a double-bracket case link to an existing blog post within the app. click the link for the other blog post. at the bottom of this other blog post, should see a "backlinks" link. click the "backlinks" link. should see a list of all pages that link to the other blog post.

Invalid function

(showerror - Function - do_invalid_function) in the URL path info, if an invalid command or function is given: "Invalid function: xxxxx" "It's not supported."

Generic post display

This will work for displaying either a microblog or blog post.

Instread of the URL containing "microblog" or "blog," the function/action word "post" can be used.

Last Blog Viewed

For each blog post viewed, the user's db table is updated that stores the blog post id number for the blog post currently viewed. when browser closed and re-opened or when user logs out and logs back in regardless of device, the last viewed blog post will be automatically displayed first. The last viewed blog post is the first thing the user sees after restarting browser with saved-login cookie set or when logging back in.

Text size

(textsize - TextSize - set_text_size) click on the five "A" links at the bottom of the website to change the font size. a cookie will be set to preserve font size on next visit after browser was closed. a user does not need to be logged in to change font size.

Themes

Initially, a dark background with light links theme existed, but at the moment, it's not available. The only theme used is the default view.

Template Includes

for blog posts. double-curly brace command around the title of an existing blog post will include the HTML content from that post into the post initiating the include command. if the tmpl. and tmpl.. commands are used in the other blog post, then only the content within those commands will be included. example: blog post A exists titled "This is Test A" blog post B wants to include content from blog post A by using: {{This is Test A} } within the post B body text. (except no space between the two right hand curly braces) the user's profile description area can also use the double-curly brace include command.

Include templates

A template article can be included into another article by surrounding the title of the template article with two curly braces.

{ {Existing Template Article Title} }

The template will be included into the article at the time the article is displayed to the user. That way changes to the template will be seen immediately the next time the article with the include is displayed to the user.

If you know you're creating a template article something like the ones listed on the Template Messages, then you can create your template article title with Template: at the start of the title. You don't have to do this, but it helps group the templates. And when you include a template article that has its title beginning with Template: you don't have to include Template: within the curly braces.

Example:

You can include the contents in article Template:Underconstruction into another article by typing

This article is currently in the middle of an expansion or major revamping.
into the other article. You can include any article into another article, by typing the full title of the article to include within the curly braces.

Template tags

If you want, you can use the opening and closing tmpl tags around the text to be included, so that only the text within the template tags will be included into another page. That way a user can provide additional info about the template within the template page but not have this additional info included into another article page.

  • tmpl. = opening template tag
  • tmpl.. = closing template tag
  • both must start at the beginning of a line. The opening tag can precede the text or exist on its own line.

Custom formatting commands

Textile like. defined in Format.pm q. and q.. tmpl. and tmpl.. hr. br. more. code. and code..

A few other formatting commands were added, and they work similar to the Textile commands.

  • q. and q.. To highlight or quote text from another source, surround it with the opening and closing 'q' tags. Both must start at the beginning of the line.
Here is some text being quoted from another article. Instead of using italics or double quotes, leave the text as is but surround it with the open and closing 'q' tags. This highlighted text will be indented a little and will have a darker gray background.

  • br. To add a blank line, start this command at he beginning of the line. It can precede text, or it can be on its own line. If the latter, Textile will surround the command with paragraph tags, which will cause a total of two blank lines to be displayed.

  • hr. Will add a horizontal rule or a long thin line that stretches across the page. Command must start at the beginning of a line. Example output:

  • tmpl. and tmpl.. Used when creating template articles that typically get included into another article. Explained further below in the template section.

Bracket case

double-bracket case surrounding the title of an existing post will automatically be turned into a link to that post. EX: [[Lake Erie West] ] (except no space between the right brackets) can also use the vertical bar to display different link text to the user. EX: [[Lake Erie West | LEW] ] will use LEW as the link display text. if post defined within double brackets does not exist, then nothing happens during PREVIEW. the text and the brackets display as is. no links. but after the post has been saved, then a draft post is automatically created with the hashtag draftstub. a link is automatically created in the formatted content where the double-bracket case was used. the stub count can be observed by the user on the user's profile page.

External links

URLs that point to other websites have the class="extlink" added to the HTML anchor tag. currently, the CSS is defined to display red link text color when mousing over an external link. obviously, not applicable to touch screens. maybe change the external link color some, so that the link can be identified on touchscreens.

Streams

Streams

(blog - Stream - show_blog_stream) (stream - Stream - show_entire_stream) (microblog - Stream - show_microblog_stream) (blogarchivepage - Stream - show_archives_month_year) (private - Stream - show_private_blog_stream) (draft - Stream - show_draft_blog_stream) show stream of all microblog and blog posts for a user. show stream of all microblog and blog posts by all users. default number of posts displayed per page = 15 (max_entries_on_page) when the number of posts in the stream exceeds max_entries_on_page, then the "Older" link appears in the lower right hand corner of page. when viewing page 2-plus, the "Newer" link appears in the lower left hand corner of page. the entire microblog post is displayed. for blog posts, content displayed includes: the link title. only the first X-number of characters of body text. "more" link if body text exceeds the X-number of characters permitted on the stream display. if showintro=no command used in body text, then display only the title and the "more" link. when the browser is resized smaller or when viewing the site on a small screen, the blog post intro text is not displayed, regardless of the showintro command. the entire microblog post, however, is still displayed.

Replies

Replies

(reply - Reply - show_reply_form) (addreply - Reply - add_reply) (replies - Reply - show_replies) (repliesstream - Reply - show_replies_stream) click reply link to get the reply form. replies are microblog posts with the same formatting and max character limitations. test formatting and max char count for a reply. add legitimate reply. view thread of replies and parent post. test reply to a reply. verify links for discussion thread and parent post within a reply thread. test replies from another user. after clicking "replies" link in nav bar, a stream of replies from other users will appear. add reply to a post created by another user.

Webmentions

Also known as remote replies. People can post their replies on their own websites and then submit their reply posts either manually or programmatically to Junco/JotHut.

A Junco/JotHut Endpoint URL exists for receiving Webmentions.

http://jothut.com/cgi-bin/junco.pl/blogpost/15851/23Oct2013/Creating-a-Webmention-blog-reply-post-at-JotHut

http://jothut.com/cgi-bin/junco.pl/blogpost/4135/21Oct2013/In-Progress-Add-webmention-client-code-to-Junco

Submitting a webmention with Curl
http://jothut.com/cgi-bin/junco.pl/blogpost/11129/19Nov2013/Junco-Curl-testing

Webmention mechanical user account exists at JotHut to enable JotHut to receive webmentions.

Example Testing:

  • http://jothut.com/cgi-bin/junco.pl/blogpost/4613/13Jan2014/What-does-mobile-first-mean-to-the-media
  • http://jothut.com/cgi-bin/junco.pl/microblogpost/9693/09Oct2013/This-a-test-webmention-source-reply-post-to-http-jothutcomcgibinjuncoplblog
  • http://jothut.com/cgi-bin/junco.pl/microblogpost/9694/09Oct2013/http-jothutcomcgibinjuncoplmicroblogpost969309Oct2013Thisatestwebmentionsou
  • http://jothut.com/cgi-bin/junco.pl/replies/4613

Etc:

  • http://jothut.com/cgi-bin/junco.pl/microblogpost/5421/21Sep2013/http-kevinbeynoncomarticle34webmentions_and_the_real_social_web-webmention-
  • http://jothut.com/cgi-bin/junco.pl/microblogpost/4636/16Sep2013/http-tantekcom2013258t1parsingwebmentionsexplanationhowtoreceive-indieweb
  • http://jothut.com/cgi-bin/junco.pl/microblogpost/4632/16Sep2013/webmention-http-gistgithubcomadactio6575229-The-form-I-put-at-the-end-of-ev

Junco code does not automatically parse a blog post and attempt to send a webmention to every external link within the post. That's way too much grinding by the code. The selective way to automatically send webmentions for links within a blog post would be to surround the response with the appropriate microformat tags. Then the Junco code would automatically send a webmention.

https://github.com/indieweb/mention-client-ruby

https://github.com/search?q=webmention

Open Graph and Microformats2

http://jothut.com/cgi-bin/junco.pl/blogpost/8450/07Oct2013/In-Progress-Add-Microformats-support

http://jothut.com/cgi-bin/junco.pl/blogpost/5411/07Oct2013/Add-hentry-microformat

Shorter URLs for Posts

Syndicating to Posts to Twitter

Currently, it's done manually by clicking the Twitter share button on each Junco/JotHut post while logged into to Twitter. It's a lo-fi approach for now.

Wiki links

Bracket case: [ [text here] ]

Bracket case but displaying different text to user: [ [Actual title text|displayed title] ]

If the article doesn't exist, a draft post is created with the hashtags "draftstub."

If the article does exists, then bracket case will be converted to a web link, pointing to the existing article.

This article is titled JotHut About. If you want to create a link in another article pointing to this help page, type [ [JotHut About] ]. Since JotHut About already exists, the bracket case will be converted to the link: JotHut About .

Camel Case linking does not exist.

Bracket case chars

#todo double-check valid chars:

  • Alphanumeric plus underscore
  • Whitespace
  • Dash
  • Period
  • Vertical bar
  • Colon
  • Apostrophe

Displayed web links

When mousing over an internal link, the link will become underlined with the link color remaining either blue for unvisited or purple for visited.

When mousing over external links, the link color is changed to red.

Used for temporary reference:

From JR's : articles
4424 words - 27907 chars - 24 min read
created on
updated on - #
source - versions



A     A     A     A     A

© 2013-2017 JotHut - Online notebook

current date: Dec 24, 2024 - 9:01 a.m. EST