Help?

Write

From Textpattern CMS User Documentation

Content sub-panels:

Figure 1: Admin-side menu showing active "Write" tab.

Write is the default panel opened when you log into Textpattern's admin-side (see Figure 1). This panel reveals the various features for managing articles on your Web site, which includes creating new articles, editing existing articles, assigning (or reassigning) articles to sections and categories, setting the time and date of articles, and various other abilities that are covered in the following description.

Contents

Panel Layout

The contents of the Write panel are arranged in three columns: left, middle and right column (see Figure 2). The items in each region are discussed in in the following sections, beginning with the middle column, which is the main editing area.

Figure 2: Write panel: Page layout with the three primary regions (columns) marked.


Write Panel Middle Column - Main Editing Area

The middle column of the Write panel is where the base creating, drafting and editing of your article takes place. There are four components of this region (see Figure 2 in the middle column) - three that constitute an article itself, and one that allows different ways of viewing that article as you draft/edit it. They are described below. (It should be noted that you must have content in at least one of the article content fields - title, body, or excerpt - before you can save an article draft, but you do not need to have all fields filled.)

Title

This field is simply where you type the title (for the most parts the main heading, but other heading systems are possible) of your article. You cannot use any formatting in this field (i.e., HTML or Textile, formatting will be added by an article form (see Forms). The Textpattern tag that is used to output the title of articles is <txp:title /> (see title).

Body

This large field is where the article is actually written (or pasted, if you prefer drafting your articles in another text editor). The Article View (see below) works in combination with this field. The primary article tag that is used to output the body of articles is <txp:body /> (see article).

Excerpt

This field is where you would add an excerpt, which is a brief bit of text about the article itself. This field is not required, but such a decision would be founded on how you ultimately wanted to establish your Web site's presentation and architecture. For example, a typical use of an excerpt is for article lists on a home page, where only a title and excerpt for each article is shown in the list; the excerpt provides a little indication about what the full article is about, and the title acts as a link to the full article itself, but when you go to the full article the excerpt is no longer seen.

In Textpattern, the excerpt is not part of the article body but rather is a discrete content item managed separately; however, like the body, you can use Textile (or HTML) to format text in the excerpt. The tag used to output the article excerpt is <txp:excerpt /> (see excerpt).

Article View

See (1). At the right of the body field are three vertical tabs labeled "TEXT," "HTML," and "PREVIEW;" these provide three different views of your article-in-progress, as described below:

  • TEXT: As indicated by the white background of the TEXT tab in Figure 2, this tab is active by default and is the one you actually draft your article in. The TEXT view works just like a regular text editor (not a word processor). To give your text formatting, you will have to know either Hypertext Markup Language (HTML), or use Textile. Textile is a remarkably simple text editing syntax that allows you to format text for the Web without having to know HTML. (More about using Textile is provided in the section Textile Help below).
  • HTML: This tab, when clicked, will show you what your article looks like in HTML format, assuming you have used HTML or Textile to do any formatting. If you have, you will see the resulting HTML syntax incorporated in your text. You cannot do any editing in this view, it is for previewing your HTML work-in-progress only.
  • PREVIEW: This tab, when clicked, will show you what your text will look like (whether you used HTML or Textile) once it is live on the Web. You cannot do any editing in this view, it is for previewing your work-in-progress only.

As you write or edit an article, you may choose to do so using Textile, or you may want to add a single image to the article before posting. The options in the left column provide help in these and other areas, so we will go over those next.


Write Panel Left Column - Options

The left column of the Write panel provides options for editing as well as content (see Fig. 3): "Textile Help" (2), "Advanced Options" (3), and "Recent Articles" (4); each covered below. All three links toggle (show and hide) additional options, when you click them.

Figure 3: Write panel: The options in the left column of the panel.

Textile Help

See (2). Since Textile is built into Textpattern, and since it is so useful for drafting articles without having to know any HTML at all, a link is provided here to assist article authors with some quick-reference to basic Textile. "Textile help" contains a short reference list of common Textile syntax (see Figure 4).

Figure 4: Textile Help expanded - showing syntax for basic Textile formatting. Help link to describe item in detail (a). "More" link to actual Textile site (b).

Each Textile item shown is followed by a little brown question mark - "?" - symbolizing a help reference for that item (see Figure 4, 2a); when clicked, a pop-up window will appear with complete details about how to use the particular Textile syntax and what it will produce. For example, see Figure 5 for what appears when the help is clicked for the "header: hn." item.

At the bottom of both the expanded Textile Help list (Figure 4, 2b) and the pop-up help (Figure 5) there is another link called "More" and "More information," respectively, which leads to the Textile reference site (txstyle.org) where complete (and advanced) information about Textile formatting can be found. Note also at the very bottom of the pop-up help window (Figure 5) there is a search feature for searching all information in the entire built-in Textpattern help.

Figure 5: Example of pop-up help (in this case for header: hn) that appears when a "?" link next to the options in the expanded Textile Help list is clicked.

Advanced Options

See (3). The second toggle-link in the left column - Advanced Options - contains a number of extended options for the particular article being edited (see Figure 6). They are described in detail here:

Figure 6: The Advanced Options menu expanded, showing 7 different advanced article options.

The advanced options column remembers its open/close state across sessions via cookie.

Article and Excerpt Markup

See (3 a+b). There are two options regarding Textile-markup: Article Markup (for the body) and Excerpt Markup (for the excerpt). By default full Textile-markup is turned on by Use Textile. You can turn off all markup by choosing "Leave text untouched". If you want a minimum of comfort you can choose Convert linebreaks - single linebreaks will be converted to linebreaks and double linebreaks will get paragraphs.

Override Form

See (3 c). The option "Override Form" offers the possibility that single articles may use a different Form than the overall form specified. Let's look at an example for a possible use of this.

In your blog, you normally publish articles which are pure text. So your default form contains only the tags for title, body etc. On every first day of the month, however, you publish a photo of your garden. For this, you need the article_image tag in your form. So you create a form called "garden_image" which, among other tags, contains article_image . Whenever you want to publish a photo along with your text, you choose "Override form" and then "garden_image" from the dropdown list.

This way, just this article will use the form "garden_image" for being displayed whereas all other articles will continue to use the default form.

Custom Fields

Custom fields are defined in Advanced preferences, which then makes them available for use here in the left column of the Write panel. The data you enter is limited to 255 characters, and is output by whatever tag constructs you create using the custom field (and possibly the if custom field) tag(s).

Keywords

See (3 e). The next option, Keywords, allows you to specify a comma-separated list of words that relate to your article. This list might be used to generate a list of keywords for search engines (using the meta_keywords tag). You may also use keywords to help locate articles later by essentially 'tagging' your articles with related words so that - when searching within Textpattern - you can more easily find what you are looking for. To add keywords, simply type them into the text field provided and separate them with a comma.

Article Image

See (3 f). The Article image option enables associating a single image with an article, as opposed to entering the image into the article itself, and is used in conjuction with article_image. This allows images to appear in the same place across many articles, yet still easily changed later.

What Can Be Done With This?

This feature could be used to power:

  • a photoblog, where a photo is associated with an article, which might contain details about where the image was taken, or what kind of equipment was used to take it,
  • a portfolio, where an illustration or a screenshot of a website is associated with an article, which contains details about the project or the client involved
  • a news site, where each article has, optionally, one main image that is always placed at the top of the article

A live example of this in use is the Textpattern home page. Each of the major sub-sections of content on that page are actually individual articles, all (with the exception of the first article) having an image (screenshot) associated with it.

How To Use It

There are two ways to assign an image to an article:

  • by ID (as it appears in the Images panel; this only works for images managed through the Textpattern Images tab)
  • by absolute url to the image, such as
    /images/imagefile.png

Once the image is associated with an article, article_image is used to display it by placing this tag within the article Form being used.

URL-only Title

See (3 g). The last advanced option, URL-only title ("URL" meaning Uniform Resource Locator), is a very handy feature that allows you to modify the Permalink URL for the article as it would appear, for example, in the the address bar of a Web browser if you were using Clean URLs. This is particularly useful if the title of your article uses non-ascii characters, such as what might be involved with certain languages.

In addition to modifying the title as it appears in the URL, this will also be the title used in the pop-up dialogue box that appears when you hover over the article title on a Web page (so long as it is displayed as a link). If you leave this field blank, the URL title will be generated from the actual article title, which is recommended for URL health reasons.

For interdependencies between article status and URL-only title read the grey box here.

Recent Articles

Figure 7: Recently modified articles' list.

See (4). The last option is Recent Articles, and there's not much to say about this option other than it toggles a list of titles for the last ten most recently modified articles (new or edited). This makes it easier to move between articles you might want to work on without actually having to jump between the write tab and the articles tab (see Articles tab).


Write Panel Right Column - Publishing Controls

Note: Especially if you like to save your work from time to time while not yet finished, you should take care of the article's status: By default it is "Live" - so using "Save" (or "Publish") in an unfinished state without altering its status to Draft (recommended) or Hidden will make an article public before its time. Pay attention!

When you are done with writing or editing an article, particularly if it's a new article, you will want to make sure you have the various controls on the right side of the write panel configured appropriately. These regard publishing an article (or keep it unpublished) in various ways. They come in two portions: Controls you always need statically at the top (Figure 8) and a portion of optional controls which you can toggle using the "More"-Link (Figure 9).

Panel Mode: New or Saved/Posted Article

There are two different states for the right column appearance depending on whether the article is new (see Fig. 8 and 9) or already has been saved before (see Fig. 10 near bottom). The settings themselves are much the same, so they will be explained as they appear for a new article, and differences pointed out in brackets (saved:alternate). Some additional elements we'll point out in "Write navigation" and "'Publish' or 'Save' Button".

There are essentially five different publishing controls to address (see Figures 8 and 9): Status, Sort and Display, Comments, Timestamp and Expires.

Figure 8: Write panel: Publishing controls for a given article - default view (upper, static part).

Status

Public (Published) or Private (Not Published): The first and most important publishing control is the article status; a series of five radio button options for indicating the status of your article (Figure 8, item 5). If you select draft, hidden or pending, your article will not be visible online, but if you select live or sticky it will be visible. The specific function of each status mode is described in following sections.

Status assignment depends on the Privileges of a user. Depending on your site's publishing objectives, or number of contributors, not every user may have the same privileges, as set in the Users panel. If multiple contributors support a site and different roles are set, it may be that some users will only be able to choose a subset of these status modes.

Draft

The Draft status means pretty much what it implies: your article is not finished, it is a draft. Select this mode if you are starting an article (or revising an existing article) but you do not expect to finish it in one sitting. By selectng draft your article will be saved to the database, but it will not be made live to the world. You can come back anytime to work on the draft article, and change the status when you are ready.

Hidden

The Hidden status might seem a bit odd, but it does have a purpose - think of it as a gaff hook to pull a bad actor off stage; in this case a "bad" (of course it needn't be "bad") article offline. In Textpattern, the Hidden status is a way to pull a live article from being viewable to the world without deleting it so that it might be revamped (or held in limbo) for an undetermined amount of time (or until a decision is made as to whether or not is should just be deleted). While Draft is used as a document status for revision control and publishing workflow, Hidden is merely a quick way to pull an article out of circulation. Note: If you have a determined time period for an article to be public, it might be better to set it "Live" and use Timestamp and Expires as needed.

Pending

The status of Pending is primarily intended for versioning activities - for example where multiple contributors are working on the same article, or where someone can finish an article, but where the article can only be published by an authorized user with a particular user role. "Pending" is the final Status that can be assigned by "Freelancer" and "Designer" - it indicates, that an authorized user may start reviewing, editing and publishing it.

As long as the article is in one of Draft, Hidden, or Pending mode, changes made to its title are assigned to its URL-only title. If you, however, gave the article intentionally a URL-only title thats different from the article's title, this field remains untouched.

Live

A live article status means that when you click the "Publish" button (all new articles will use a button that reads "Publish", after that, the button will read "Save") the article will be posted for the world to see, so you generally want your article in question to be pretty much done if you select this mode. (This status and the next one, sticky, are the only two publicly-viewable modes.) However, you can always unpublish an article that has been made live by coming back to the write panel and selecting the Hidden status above (or deleting it altogether).

For those privileges who have the rights to assign Live, this button will be selected by default whenever you start a new article. "Freelancer" and "Designer" aren't privileged to assign "Live". Their articles have to be published by higher privileges. Once published they cannot modify even own articles any longer.

Sticky

A sticky article is also considered 'live'; however, it won't show up with your other live articles in normal article flow (such as those output with <txp:article />), nor will it appear in any article output lists you might have. The sole purpose of making an article sticky is to give it the status (or rather the appearance) of being static on a page. The sticky status is intended for things like "about" pages, articles that are pinned to the top of a page, or snippets of text that are displayed on pages outside the regular flow of articles.

Same privilege restrictions apply for "Freelancer" and "Designer" as in Live.

To implement a sticky article you need to do two things:

  1. Write the article you want to be sticky.
  2. Create a code snippet for the sticky output and insert it in the Page template you want the sticky article to appear.

A code snippet might be something like this (though certainly not the only structure):

<txp:if_article_list>
   <!-- display the sticky article -->
   <txp:article form="myshortform" status="sticky" />
</txp:if_article_list>

<!-- now the regular article list --> 
<txp:article limit=5 />

Generally speaking, what the snippet of code above is saying is...'if an article list, display the sticky article using the form called "myshortform" - then underneath the sticky article, output regular article flow but only show the last five articles.'

Sort and Display

Category

Assign Categories See (6). This control - provided for assigning categories - is composed of two drop-down menus (empty by default) and an "edit" link. Assigning categories of course only works if there is at least one article category in the Categories panel (there are three sample ones in a default install). The "edit" link will open the Categories panel, where you can create or edit categories. The drop-down menus will both list all categories by their title. This basically allows you to put an article in up to two different categories, which you can then manipulate later according to your planned site architecture and content presentation (such level of discussion is out of scope here). (For saved articles this control will show existing category assignments.)

Section

Section Assignment See (6). In Textpattern each article must be assigned to a Section (see Sections). This control provides a drop-down menu to select the Section that you want. If you need to create or modify a section, you can get to the Sections panel using the "edit" link. For a new article the default section is automatically preselected. You can override this assignment by selecting another Section of your choosing. (For saved articles the assigned section will be selected and displayed in the drop-down menu.)

There are two Sections provided in a default install of Textpattern: "article" (which here is the "default section" mentioned above, see Figure 9, number 3; it is used for Textpattern's base article flow), and "about". These sections are simply provided because these are often desired in Web sites and the folks at Textpattern are saving you a small step by creating them for you; you can use them (though you may have to modify their settings depending on what you want) or delete them, it is up to you.

Sections basically control in what area of your Web site your article will be displayed. You can use Sections in combination with Categories to create very diverse content management strategies, giving your Web site visitors the impression of a structured, hierarchical Web site architecture. More description of Sections is out of scope here, but review later documentation chapters for more insight.

Figure 9: The write panel "settings" for a given article - more settings (lower, toggle-part).

More

Additional Controls Toggle See (7). There are more settings, which will be opened with the "More"-Link (7). You can toggle them by clicking on "More".

Comments

Important note: The Comments control on the write panel is actually a second-level setting for managing comments at per article level; you should have already configured your settings for first-level (site-level) comment management, which is handled in the Basic Preferences panel at "Publish" and "Comments". There you will find different Comments settings that need your consideration about how to handle comments for all articles in your site by default. If Publish "Accept comments" is "No", no Comments control will appear in the Write panel. Two of the settings - "On by default?" and "Default invite" - will determine the defaults in the Comments control at article level. Here, as described below, you can adjust the behavior as you desire for a particular article.

Comments Pointer to Comments control controls two things: With a pair of on/off radio buttons first you either accept or deny comments for the given article. Second is an "Invitation" field that allows you to customize the text for the link that users will see if comments are "on".

The comment link itself will lead to the location in your site where a visitor can actually add a comment to your article. By default the link text is "Leave Comment", but other possibilities might include: "Let's hear it!", "Speak Up", "Respond", "Got something to say?", etc. - whatever you want. If you choose to have a single invitation for use with all of your articles then it is easiest to just set that value in your site-level Comments settings in the Preferences panel.

Timestamp

Time Management See (9). This part might be considered two different functions: Timestamp and Timecontrol. They are both managed (and discussed) here.

By default, at the moment of opening the Write panel Textpattern adds the current date and time to the text boxes provided, thus marking the beginning of work. Unless you specifically indicate a different date and time this time will be saved when publishing the article, thus documenting the beginning of your work. If you rather want the current time when finally publishing (or re-publishing) the article ("Live" and public), then you should mark the check box "Set timestamp to now" (saved: "Reset time to now") before you click "Publish" or "Save" in order to set the article public. This option will always establish the date and time at the moment you click the "Publish" or "Save" button as the article's "publish"-timestamp, no matter what status you give it.

To change your article's date and time value to something other than the current time, leave the aforementioned box unchecked and type in the date and time you want in the "or publish at" (saved: "Published at") text boxes provided. If the time is in the future and the Status is "Live", the article will automatically be published at the given time.

Documentary or Historical Aspect - Time of Origin

If you are interested in documenting the time when an article has been originally published (whether by its true creating time or by an arbitrary time of first publishing), you shouldn't update the timestamp to "now" when modifying. The timestamp defines the order of articles when an article list is created by publishing time - a change thus will reflect in the sequence of articles.

If you nevertheless want to indicate a "last modified" date, you can use modified in your article forms.

If you need the timestamp for publishing schedules apart from marking an origin, you need to indicate the origin otherwise: If you do not modify after your "origin" date, you could use modified as an indicator. Else you could provide a custom field (e.g. "first_published") for that task.

Expires

Advanced Time Management See (10). In the same way you can set a deliberate publishing date/time for an article, you can also set a time, when it will expire and thus vanish (or unpublish) from particular page or the whole website - depending on your site's setup.

Note: Using expire-preferences and a set of expire-tags you can achieve a sophisticated way of publishing and removing articles though at the same time keeping them active for permanent links or an archive.

Write Panel Navigation

As described earlier, the right column changes appearance a little bit when you work on articles you have already saved (Figure 10). Different labels have been marked above. There are a few additions described below.

Figure 10: Write panel appearance for articles already saved in Textpattern.

On the right side of the title there is a new link "View". It will open the public-side view of the current article in the same browser window.

See (11 a). At the top of the right column there is a new link "Create new". It will abandon all unsaved edits of the current article and open a new empty Write panel.

See (11 b). Two navigation buttons - previous and next (when applicable) - let you navigate from one article (in the article catalogue) to another without having to leave the write panel. (Another option is to select articles from under the Recent Articles link on the right side of the panel, as already discussed in an earlier section.) The navigation buttons will rotate through your articles catalogue from the reference point of the article you happen to be viewing at the time. When you click the previous button you will move to the article that is one above the one you are at in the catalogue. When you click the next button you will move down one article in your catalogue.

"Publish" or "Save" Button

See (11 and 11 e). The last thing to be aware of has to do with the button that publishes/saves your article and settings. Basically, there are two button labels you will see when working in the write panel; "Publish" (new article state) and "Save" (existing article state).

When drafting a new article, the button will read as Publish. This might be a bit confusing because the word publish would suggest your article is going directly live to the world when you click this button; however, that will only be true if you set the article's status to be either Live or Sticky, as already discussed earlier. If this was a new article, and you changed your status to draft (for example), then this button would still read as "Publish" (even though you were just saving a draft), and not go live to the world. Basically, the Publish label is the default label.

Once you publish an article for the first time, no matter what the status (Draft, Live, ect.), then the next time you come back to edit your article in the write panel, the button will change to read as "Save," as it does in Figure 10 (e). The Save button will behave exactly the same as the Publish button, despite whatever article status you happen to want to select (if not Live).

When considering this button situation, it probably would make more sense to just have a "Save" button in all cases, but that is not how it currently works. At least the "Publish"-state before you "save" your work for the first time - probably when still unfinished - could beware you of inadvertently publishing rough work: When the button reads "Publish" better look twice if the Status is correct and really should be "Live".

Messages

Figure 11: Message area.

See (12). When publishing or saving an article, Textpattern gives a feedback in the message area top left beneath "Textpattern" (see Figure 11). When an article will be public (live or sticky), message reads "Article posted." - when another Status (Draft, Hidden, Pending) is active, message is "Article saved as status mode.". Sometimes there will be an additional info and need to modify something - most likely dealing with an identical URL, e.g. "Article posted. The same URL-only title is used by 2 different articles.".

Translations [?]