Topics

Figure: depiction of Web Home, Reference Manual, Managing Topics, Managing Webs, Main Features topics contained in the System web
Topics are the basic building block of a Foswiki site. You may be more familiar with the term pages, documents or articles in other software; however, Foswiki's topics traditionally serve more purposes than the equivalent in other systems. Topics can only exist inside a web. The topic you're reading now is Topics And Webs.

A Web is a collection of topics (and other webs, known as subwebs). Webs are containers and by themselves cannot store information; only topics can do that. You may be more familiar with the term Namespaces in other wiki software, but Foswiki's webs are more like directories and folders in your computer's operating system. There is no common "root" web. The Topics And Webs topic you're reading now is contained in the System web (its complete, fully qualified name is System.Topics And Webs).

Anatomy of a Topic

Each topic has:
  • name
    • topics in a given web have unique names to identify them
    • topics with a Wiki Word name are automatically linked (as opposed to [[forced bracketed links]] - see WikiSyntax to learn more)
    • there are restrictions on topic names; see topic naming rules
    • a topic's fully qualified name is prefixed with the web it is contained in, for example the topic you're reading now may be referred to as System.Topics And Webs
      • fully qualified names are used when a link is being made to a topic in another web
  • content
  • attachments
    • topics may have one or more file attachments
  • DataForm
  • access controls
    • control who can view, edit, rename, move or delete topics
    • set permissions for individual users or user groups
    • override default permissions inherited by the web or site
  • revisions
    • changes are automically recorded
    • change history shows authors, dates, and allows comparison between any two versions
    • revert to older versions
  • containing web
    • every topic must be contained within a web
    • list of webs at Webs Table
  • meta-data
    • hidden contextual data stored within each topic
    • Example: parent topic
      • new topics are automatically made a "child" of the topic it was created from
      • parent relationship allows hierarchical, parent-child navigation
      • See Figure of System web
  • backlinks

Creating and editing topics

Foswiki makes it easy to add and edit topics or link between them.

To edit: click Edit in the toolbar which should be present at the top and bottom of each page (assuming default Pattern Skin). An edit screen appears. Use the Edit Help button if you need it.
  • Click Preview to see how your edit looks.
  • Click Save to save.

To add a new topic there are three ways in the default Pattern Skin:
  1. Create a link to the topic which doesn't exist yet, e.g. by editing a topic and typing a Wiki Name. When the topic is saved, the link will be shown with a ?: click the ? and a new edit window appears.
  2. Navigate to the topic which doesn't exist yet, e.g. by typing the name of topic in the JumpBox. Foswiki should display a screen which invites you to create the topic.
  3. Click the Create New Topic link in the Web Left Bar links down the left side of the page (assuming default Pattern Skin). Foswiki should display a screen which invites you to create the topic.

Topic Names

The best strategy is to use Wiki Words for your topic names. In this way, linking is automatic. However, if non-Wiki Word names are required, you can use [[bracketed links]] to force a link to a non-standard topic name (see WikiSyntax). Forced links are subject to some restrictions and the actual topic name may not be identical to what was entered into the forced link.

  • The first letter of each "word" will be automatically capitalized
  • Spaces are compressed out of the topic name
  • The following special characters are removed:
    • Any other "whitespace" characters
    • * (Asterisk)
    • ? (Question mark)
    • ~ (Tilde)
    • ^ (Caret / Circumflex)
    • \ (Backslash)
    • $ (Dollar-sign)
    • @ (At-sign)
    • % (Percent-sign)
    • `'" Quotes (Open-quote, Close-quote/Apostrophe, and Double-quote)
    • & (Ampersand)
    • ; (Semicolon)
    • | (Vertical line)
    • <> (Less and Greater signs)
    • [] (Open and close square brackets)
    • And any ASCII control characters (Hex x00-x1f)
Example: If you enter [[my special-topic @here]], you will see my special-topic @here, but the actual topic created will be MySpecial-topicHere.

Note that if you use the Topic Creator, Wiki Word rules are strictly enforced and the resulting topic name would be MySpecialTopicHere For more details on forced links, see EditingShorthand

IDEA! The naming rules may be different for your installation; ask the wiki administrator who may have customised the {NameFilter} expert option under Security and Authentication in configure

Reverting, renaming, moving and deleting topics

See FAQDelete Or Rename ATopic and Managing Topics

Anatomy of a web

If a user navigates to a Foswiki site without specifying a web, the default Accueil will be displayed.

Each web has:

Renaming, moving and deleting webs

See Managing Webs


Related Topics: User Documentation Category, Admin Documentation Category, Managing Topics, Managing Webs
Topic revision: r1 - 18 Sep 2010, ProjectContributor
 
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Telem? Send feedback