TWiki/TWikiTopics.mdwn

   1 # <a name="TWiki Topics"></a><a name=" TWiki Topics"></a> TWiki Topics
   2
   3 <div>
   4   <ul>
   5     <li><a href="#Characteristics"> Characteristics</a></li>
   6     <li><a href="#Creating and editing topics"> Creating and editing topics</a></li>
   7     <li><a href="#Other features"> Other features</a></li>
   8     <li><a href="#Renaming, moving or deleting top"> Renaming, moving or deleting topics</a></li>
   9     <li><a href="#Reviewing and Reverting"> Reviewing and Reverting</a></li>
  10   </ul>
  11 </div>
  12
  13 The basic building block of a TWiki site is called a **_topic_**, identified by a unique, hopefully descriptive, %SYSTEMWEB%.WikiWord title. It may seem easier just to call them pages, but specifically a topic is the content of a page. The distinction seems small but will become more important as your skill using TWiki increases. [[TWikiSites]] are built using topics.
  14
  15 ## <a name="Characteristics"></a> Characteristics
  16
  17 A TWiki topic is a rich information unit. **Each** topic has:
  18
  19 - name
  20   - instantly identify what the topic is about
  21   - link to it from other topics just by typing in its [[WikiWord]]
  22 - content
  23   - edited by simply clicking the [[edit link|Main/WebHome#PageBottom]]
  24   - enter plain text, leaving a blank space between paragraphs like e-mail (all you need)
  25   - enter simple TWiki shorthand to represent complex HTML and special TWiki variables
  26   - enter HTML if you are familiar with it
  27   - include links to other topics, URLs, Web sites, files, images, sounds, or anything else you can put on a regular Web page
  28   - handy pop-up quick reference
  29   - do all of this through whatever web browser you are familiar with
  30 - [[access control|SYSTEMWEB/TWikiAccessControl]]
  31   - independently determine who can see, edit, rename, move or delete topics
  32   - set permissions by individual users and user groups
  33   - over-ride topic, TWiki web or site
  34 - revision control
  35   - topic changes are automatically saved
  36   - efficiently stores every change made to the original version
  37   - lets you compare and retrieve changes between any two versions, or review them all
  38   - displays any previous version as a regular Web page or as raw topic text
  39 - TWiki web
  40   - a TWiki organizational unit to which the topic belongs
  41   - relevant when searching for a topic, referencing it or typing in its URL
  42 - meta-data
  43   - hidden contextual data stored within each topic.
  44   - parents
  45     - automatically links a new topic as the "child" of the topic it was created from
  46     - hierarchical, parent-child navigation
  47     - allows manual assignment of parent topic from a list of all topics in the local web
  48     - offers navigation by topic parents
  49 - backlinks
  50   - named referred-by (Ref-By)
  51   - lists all topics that reference the current topic
  52
  53 Features that can be used by topics and sites include:
  54
  55 - [[TWiki Skins|SYSTEMWEB/TWikiSkins]] to customize the look of headers and footers when topics are converted to Web pages for display:
  56   - default and user selectable per session
  57   - fully configurable look and feel
  58   - apply skins across an entire TWiki web, or to a single displayed page
  59   - use included skins and easily create new ones
  60   - try the <code>**Printable**</code> skin below: stripped down headers and footers suitable for clean hard copy
  61 - plug-ins
  62   - new feature packages
  63   - developer community evolving existing and new capabilities
  64 - add-ons
  65   - enhanced capability without an interface to users
  66 - [[FileAttachment]]
  67   - upload files through your browser to the TWiki server
  68   - attach any type of file (documents, images, applications) for viewing online, storage or sharing downloads with others
  69   - upload revisions of existing files with automatic backup of all previous revisions
  70 - formatted search
  71   - embedded searches of topics, data and meta-data, optional regular expressions
  72   - custom formatting for outputting lists or tables, optional layout, headings, summary, etc.
  73 - variables
  74   - similar to a command line context with site wide and locally defined variables
  75   - over-ride topic, TWiki web or site
  76 - [[forms|SYSTEMWEB/TWikiForms]]
  77   - store database-style info alongside the free-form topic content
  78   - accesses meta-data
  79   - use text fields and boxes, radio buttons, pulldown selector menus, checkboxes
  80   - create your own forms to tag topics to later search, sort and display
  81 - [[renaming, moving, and deleting|Main/WebHome#RenamingTopics]]
  82   - rename a topic and automatically update all of the links to it, site-wide
  83   - move a topic from one TWiki web to another
  84   - safely delete a topic to a special Trash web (invisible, but recoverable from the Web server if necessary)
  85 - many more features...
  86
  87 The configuration of your TWiki site, skins and your personal user account can modify the way these features are used and presented to you.
  88
  89 <a name="EditingPages"></a>
  90
  91 ## <a name="Creating and editing topics"></a> Creating and editing topics
  92
  93 A primary purpose of TWiki is to make it incredibly easy for you to add and edit information on existing topics, create new topics, and link between TWiki topics.
  94
  95 - **To modify a topic**: click the <code>**Edit**</code> link in the toolbar at the bottom left of every page (using the Default skin). An editing window appears. Type away. Use the [[GoodStyle]] and [[TextFormattingRules]] links to get pop-up window help.
  96   - Click <code>**Preview Changes**</code> to see how your edit looks.
  97   - Click <code>**Save Changes**</code> to save.
  98
  99 - **To add a new topic**: the simplest way is to type a new [[WikiName]] in an existing topic, while you're in edit mode. When the topic is saved, the new name will appear highlighted, with a **?** at the end: click the **?** and a new edit window appears. Enter, preview and save as usual. The new topic now exists.
 100   - Go back to the topic where you started, and you'll see the **?** has disappeared, and your [[WikiWord]] name is now a regular link. Type it anywhere on any topic in that web, and it will be turned into a link.
 101   - %H% **One little links rule: each topic, and its [[WikiWord]] link, belong to one unique web only.** To link _between_ webs, you must first enter the topic's web name. <br />**_Example:_** This is %TOPIC%, in the <code>**TWiki**</code> web, so that's all you need to type on any topic in this web. But to link to %TOPIC% from a topic in the <code>**%USERSWEB%**</code> web, you have to type <code>**%SYSTEMWEB%.%TOPIC%**</code> - <code>**Webname.TopicName**</code>. It's easy.
 102
 103 Another way to add a topic is to type a new topic name in the Go box or an unknown topic URL. You can type in either a [[WikiName]] to create the topic in the current web or Web.TopicName to create a topic in a different web than the current page. Topics created with the Go box or URLs do not have parent meta-data defined.
 104
 105 <a name="OtherFeatures"></a>
 106
 107 ## <a name="Other features"></a> Other features
 108
 109 The color-coded toolbar at the bottom of every topic displays a series of links, including:
 110
 111 - <code>**Attach**</code> - pops a new screen for [[FileAttachments]]
 112 - <code>**Backlinks**</code> - displays all the TWiki topics with links to the current topic
 113 - <code>**History**</code> - generates a page showing every change made to the current topic, with names, dates, and changes made (diffs)
 114 - <code>**r3 &gt; r2 &gt; r1**</code> - view most recent revision and changes
 115 - <code>**More**</code> - opens up a new screen containing additional controls
 116
 117 It looks complicated, but the basics you need to begin with are very simple to use. The flexible and optional features are ready when you care to learn about them - the only way to confuse yourself or your site set-up and users is by using features you really don't need. Unlike the usual expensive, complex collaboration and project management packages, TWiki is fully functional and effective just by typing in text and making [[WikiWord]] links. All the additional features are there, but only if you need them!
 118
 119 - Some controls are self-explanatory and also include instructions and help links.
 120 - **Experiment**. You can always <code>**Cancel**</code> an edit or (using revision control) go Back whenever you like.
 121 - Get **in-depth info** from the [[complete documentation|SYSTEMWEB/WebHome]], including the User's Guide, Configuration Manual and TWiki Reference.
 122
 123 <a name="RenamingTopics"></a>
 124
 125 ## <a name="Renaming, moving or deleting top"></a> Renaming, moving or deleting topics
 126
 127 You can rename, move and delete individual topics by clicking <code>**More**</code> on the control strip at the bottom of every page. The access settings for a topic, web or entire site may be disabled for one or more of the three options, depending on your site set-up and access permissions.
 128
 129 1. Go to the top you want to change, click <code>**More &gt; Rename/move**</code>
 130 2. **To move or delete:** select the target web (<code>**Trash**</code> to delete)from the pull-down menu (otherwise, leave on the current web)
 131 3. **To rename:** fill in a new [[WikiName]] (otherwise, leave the current topic name)
 132 4. **To update links:** From the list of topics that show links to the topic you're changing, uncheck each entry you DON'T want to update - only checked links will be updated;
 133 5. Click <code>**Rename/move**</code>: the topic is renamed and/or moved, and the checked links to the topic are updated.
 134   - Any problems are listed - take note, and you can fix them later.
 135   - If a linked topic can't be updated (it may be locked because someone's editing it), an alert will appear. You can update missed topics later by again pressing <code>**Rename/move**</code>.
 136
 137 **_%H% Note:_** Deleting means moving a topic to the Trash web. Since all webs share the one Trash, name conflicts may come up.
 138
 139 <a name="RevisionRollback"></a>
 140
 141 ## <a name="Reviewing and Reverting"></a> Reviewing and Reverting
 142
 143 RCS revision control automatically saves all topic changes. To look at earlier versions of a topic, click on `Diffs` link in topic commands. If you would like to revert to an earlier version or reclaim part of an earlier version, just copy from the old topic revision to the current topic revision. This is a step by step set of instructions:
 144
 145 1. In the `Diffs` view, take note of what version of the topic you want to reclaim and then return to `View`.
 146 2. Select `More` in the topic commands.
 147 3. Under "View previous topic revision," enter the version number you want to reclaim and check "raw text format." Then click on "View revision."
 148 4. Select either the portion of that version you want to reclaim or the entire text of the topic if you want to revert completely to that version. Select `Copy` under your browser's `Edit` menu.
 149 5. Return to the most recent version of the topic and select `Edit` from the topic commands.
 150 6. Either paste in the portion of the topic you wish to reclaimed or replace the entire text with the text you copied from the earlier version.
 151 7. Save the topic.
 152
 153 See: [[ManagingTopics|Main/TWikiDocumentation#Managing_Topics]] for more details.
 154
 155 ----
 156
 157 **_Related Topics:_** [[UserDocumentationCategory]], [[AdminDocumentationCategory]]