/
TopicsAndWebs.txt
142 lines (124 loc) · 9.23 KB
/
TopicsAndWebs.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
%META:TOPICINFO{author="ProjectContributor" date="1231502400" format="1.1" version="$Rev$"}%
%META:TOPICPARENT{name="UsersGuide"}%
---+!! 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
* changes to attachments are automatically recorded
* [[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, Eg. 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, Eg. 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)
* ==<>== (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>
---+++ Revision numbers
Topic and attachment versions are identified by positive, non-zero, integer numbers. Older revisions always have smaller numbers, but numbers cannot be assumed to be sequential, nor can you assume that the first revision of a topic will be revision 1. For example, you might have a topic history that runs like this:
=84 > 95 > 1001 > 7690=
where 84 is the first version and 7690 the most recent.
#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, IE. 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, IE. =Sandbox/MySubWeb/=. Without the trailing slash, Foswiki tries to display the _topic_ named =Sandbox.MySubWeb=
* WebPreferences topic
* sets PreferenceSettings to be inherited by all contained topics, EG. [[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
%META:FILEATTACHMENT{name="diagram.png" version="1.1"}%