Topics
What are Topics and Webs?
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
TopicsAndWebs.
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
TopicsAndWebs topic you're reading now is contained in the
System web (its complete,
fully qualified name is
System.TopicsAndWebs).
Anatomy of a Topic
Each topic has:
- name
- topics in a given web have unique names to identify them
- topics with a WikiWord name are automatically linked (as opposed to
[[forced bracketed links]]
- see EditingShorthand 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.TopicsAndWebs
- 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
- changes to attachments are automatically recorded
- 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 SiteMap
- 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
PatternSkin). 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
PatternSkin:
- Create a link to the topic which doesn't exist yet, e.g. by editing a topic and typing a WikiName. When the topic is saved, the link will be shown with a ?: click the ? and a new edit window appears.
- 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.
- Click the
Create New Topic
link in the WebLeftBar links down the left side of the page (assuming default PatternSkin). Foswiki should display a screen which invites you to create the topic.
Topic Names
The best strategy is to use
WikiWords for your topic names. In this way, linking is automatic. However, if non-
WikiWord names are required, you can use
[[bracketed links]]
to force a link to a non-standard topic name (see
EditingShorthand). 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: (May be different in your installation)
- 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,
WikiWord rules are strictly enforced and the resulting topic name would be
MySpecialTopicHere
For more details on forced links, see
EditingShorthand
Revision numbers
Topic and attachment versions are identified by positive, non-zero, integer numbers. Versions start with 1 and are sequencial.
Reverting, renaming, moving and deleting topics
See
FAQDeleteOrRenameATopic and
ManagingTopics
Anatomy of a web
If a user navigates to a Foswiki site without specifying a web, the default
User will be displayed.
Each web has:
- name
- topic naming rules apply to web names
- there is no ability to refer to subwebs with a relative path, i.e. they must always be fully qualified - referred to in full, with the parent web(s) prefixed
- the '.' and '/' characters serve as path delimiters to a web or topic
- example: Sandbox/MySubWeb/MySubSubWeb.MyTopic
- it is possible in Foswiki to have a subweb which is the same name as a topic. For this reason, if there is a web named
Sandbox/MySubWeb
, navigating to it must be done so using a trailing slash, i.e. [[Sandbox/MySubWeb/]]
. Without the trailing slash, Foswiki tries to display the topic named [[Sandbox.MySubWeb]]
.
- Disambiguation of identical web and topic names using the trailing slash is only active within
[[Square bracket links]]
.
- WebPreferences topic
- WebHome topic
- the home topic for the container web. It is also the default topic Foswiki will display if a user navigates to a web without specifying a topic name.
- Utility topics (from the _default template web):
- _default.WebAtom
- _default.WebChanges
- _default.WebCreateNewTopic
- _default.WebIndex
- _default.WebLeftBar
- _default.WebNotify
- _default.WebPreferences
- _default.WebRss
- _default.WebSearch
- _default.WebSearchAdvanced
- _default.WebTopicList
Renaming, moving and deleting webs
See
ManagingWebs
Related Topics: UserDocumentationCategory,
AdminDocumentationCategory,
ManagingTopics,
ManagingWebs