TopicsAndWebs < System

---+!! Topics
%TOC%
<div style="float: right; width: 307px; padding-left: 1em;">
#SystemWebFigure
  <div style="padding-bottom: 1em;"> *Figure:* depiction of WebHome, ReferenceManual, ManagingTopics, ManagingWebs, MainFeatures topics contained in the System web</div>
  <img src="%ATTACHURLPATH%/diagram.png" width="307px" height="438px"/>
</div>
#TopicDefinition
__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 %TOPIC%.

#WebDefinition
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 %TOPIC% topic you're reading now is contained in the [[%HOMETOPIC%][%WEB%]] web (its complete, _fully qualified_ name is [[%WEB%.%TOPIC%]]).

---++ 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 =[<nop>[forced bracketed links]]= - see [[WikiSyntax#Internal_and_external_links][WikiSyntax]] to learn more)
      * there are restrictions on topic names; see [[#TopicNames][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 [[%WEB%.%TOPIC%]]
         * _fully qualified_ names are used when a link is being made to a topic in another web
   * content
      * you're reading the topic text of %TOPIC% right now
      * use WikiSyntax (see TextFormattingRules) and [[Macros][macros]] to write rich topic content
   * [[FileAttachment][attachments]]
      * topics may have one or more file attachments
   * [[DataForms][DataForm]]
      * topics may have a [[DataForms][DataForm]] attached to them, which specifies [[MetaData][metadata]] fields that users may fill. This data may be [[QuerySearch][queried]] and [[FormattedSearch#Table_showing_form_field_values_of_topics_with_a_form][reported]] (see the [[FrequentlyAskedQuestions]] application as an example)
   * [[AccessControl][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
   * [[CompareRevisionsAddOn][revisions]]
      * changes are automically recorded
      * change history shows authors, dates, and allows comparison between any two versions
      * [[ManagingTopics#RevisionRollback][revert to older versions]]
   * containing web
      * every topic must be contained within a web
      * list of webs at WebsTable
   * [[MetaData][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 [[#SystemWebFigure][Figure of System web]]
   * [[?template=backlinksweb][backlinks]]
      * a list of all topics that reference a given topic (see <a href="#topic-actions" class="foswikiLink">"%MAKETEXT{"More topic actions"}%"</a>)

#EditingPages
---+++ 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:
   1 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.
   1 Navigate to the topic which doesn't exist yet, e.g. by typing the name of topic in the [[GoBox][JumpBox]]. Foswiki should display a screen which invites you to create the topic.
   1 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.

#TopicNames
---+++ 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 =[<nop>[bracketed links]]= to force a link to a non-standard topic name (see [[WikiSyntax#Internal_and_external_links][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)
      * ==&lt;&gt;== (Less and Greater signs)
      * ==[]== (Open and close square brackets)
      * And any ASCII control characters (Hex x00-x1f)
*Example:* If you enter ==[<nop>[my special-topic @here]]==, you will see ==[[my special-topic @here]]==, but the actual topic created will be ==<nop>MySpecial-topicHere==.   

Note that if you use the [[WebCreateNewTopic][Topic Creator]], WikiWord rules are strictly enforced and the resulting topic name would be ==<nop>MySpecialTopicHere== For more details on forced links, see [[EditingShorthand#HeRe][EditingShorthand]]

<blockquote class="foswikiHelp">%I% The naming rules may be different for your installation; ask the [[mailto:%WIKIWEBMASTER%][wiki administrator]] who may have customised the ={NameFilter}= expert option under =Security and Authentication= in [[%SCRIPTURLPATH{"configure"}%#Environment$SecurityAndAuthentication][configure]]</blockquote>

#RenamingTopics
#RevisionRollback
---+++ 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 [[%USERSWEB%.%HOMETOPIC%][%USERSWEB%]] will be displayed.

Each web has:
   * name
      * [[#TopicNames][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: [[%SANDBOXWEB%/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 =%SANDBOXWEB%/MySubWeb=, navigating to it must be done so using a trailing slash, i.e. =%SANDBOXWEB%/MySubWeb/=. Without the trailing slash, Foswiki tries to display the _topic_ named =%SANDBOXWEB%.MySubWeb=
   * WebPreferences topic
      * sets PreferenceSettings to be inherited by all contained topics, e.g. [[AccessControl][access controls]], and:
         * =FINALPREFERENCES= to prevent subwebs and topics from overriding inherited PreferenceSettings
         * =WEBFORMS= to specify a list of DataForms that users should be able to attach to contained topics
         * =WEBCOPYRIGHT= to customise copyright message for all contained topics
      * provides a link to the [[ManagingWebs#RenameWeb][rename and delete web]] utility
   * %HOMETOPIC% 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.WebHome][_default]] template web):
%SEARCH{
  "1"
  type="query"
  nonoise="on"
  web="_default"
  excludetopic="%HOMETOPIC%"
  format="      * $topic"
  separator="$n"
}%

---+++ Renaming, moving and deleting webs
See [[ManagingWebs]]
<!-- %JQREQUIRE{"chili"}% -->

---
*Related Topics:* UserDocumentationCategory, AdminDocumentationCategory, ManagingTopics, ManagingWebs
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	diagram.png	manage	0.1 K	01 Jan 1970 - 00:00	UnknownUser
This topic: System > WebHome > UsersGuide > TopicsAndWebs
Topic revision: 18 Sep 2010, ProjectContributor (raw view)
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback