TwentyMinuteTutorial < System

---+!! 20 Minute Tutorial

This step-by-step, hands-on tutorial gets you up to speed with all the Foswiki basics...

%TOC% 
%STARTINCLUDE%

---++ 1. Get set...
Open two browser windows, so that you can follow these steps in one window, while trying things out in the other.

---++ 2. Take a quick tour...
A Foswiki site is divided into webs; each one usually represents one area of collaboration. You can navigate the webs from each web page; by default, those links are located either in the upper part of a page, below the site logo or in the menu on the right hand side. 
   * Each web has hyperlinked topics, displayed as pages in your browser.
   * The home page in each web is the %HOMETOPIC% topic.
   * To browse a web, just click on any highlighted link. These links are called WikiWords and comprise two or more words with initial capitals, run together.
   * Follow the WikiWord link and learn what it is.
   * If you know the name of a topic, you can jump directly to it by typing its name into the *Jump* field on the top of a page. Type =WebSearch= to jump to the search page.
   * You can search each web. Enter a search string into the *Search* field on the top of a page. Foswiki searches for an exact match
   * Advanced Search lets you select different search types, including database-style [[QuerySearch][Queries]] and even RegularExpressions.

<blockquote class="foswikiHelp">%T% Do not confuse the *Jump* field with the *Search* field.</blockquote>

---++ 3. Open a private account...
To edit topics, you need to have a Foswiki account. 
   * Go to the UserRegistration page to create your own Foswiki account. Fill in a couple of lines and you're set!

---++ 4. Check out Foswiki users and groups.
   * Go to the %USERSWEB%.%WIKIUSERSTOPIC% topic in the %USERSWEB% web; it has a list of all users of Foswiki. Your WikiName will be listed after you register.
   * Go to the %USERSWEB%.WikiGroups topic in the %USERSWEB% web; it has a list of groups which can be used to define fine grained AccessControl in Foswiki.

---++ 5. Test the page controls...
The control strips at the top and/or bottom of the page have a collection of icons or links that allow you to take various actions. Different skins show different links, but most will have some or all of the following: 

   * ==[Edit]== - edit an existing topic (discussed later)
   * ==[Attach]== - attach files to a topic (discussed later)
   * ==[Print version]== - goes to a stripped down version of the page, good for printing
   * ==[History]== - topics are under revision control - =History= shows you the complete change history of the topic, for example, who changed what and when
   * ==[View wiki text]== - show the source text's WikiSyntax without editing the topic
   * ==[More topic actions]== - topic additional controls, 
      * view, compare or restore a topic revision
      * rename/move
      * setting the topic's parent.
      * set a topic preference

---++ 6. Create a new topic and edit an existing one
There are two different ways to create a new topic:
   1 [[#FromScratch][Create a topic from scratch.]]
   1 [[#FollowALink][Navigate to a topic that does not yet exist.]]

#FromScratch
---+++ 6.1 Create a topic from scratch
We are going to create a new topic from scratch first, before having a look at the second alternative:
   * Go to the [[%SANDBOXWEB%.WebHome][%SANDBOXWEB% web]]. This web provides and area where you can make changes and try it all out at will. 
   * Click the ==[Create New Topic]== link in the main menu; it is normally located on the left side of a page. A new page will open where you put the name of the new topic you are going to create. This name will also be used to link from one topic to another. For example, the name of this topic is %TOPIC%.
   * Enter a name for the new topic (preferably a WikiWord), for example =MyFirstTopic= (if it says that this topic already exists, just choose a different one). After that, click =[OK]=.

See also the following screenshot:
#ExampleCreateForm
<form name="newtopicform" id="newtopicform">
<div class="foswikiFormSteps">
<div class="foswikiFormStep">
---+++ !!Topic name:
<p>
<input type="text" class="foswikiInputField" name="topic" id="topic" size="40"  value="" />
</p><p><input type="checkbox" id="nonwikiword" name="nonwikiword"  /><label for="nonwikiword">Allow non WikiWord for the new topic name</label><br /> It's usually best to choose a WikiWord for the new topic name, otherwise automatic linking may not work. Characters not allowed in topic names, such as spaces will automatically be removed.</p>
</div>
<div class="foswikiFormStep">
---+++ !!Topic parent:
<p>
<input type='text' size='40' name='topicparent' class='foswikiInputField' value='WebHome' />&nbsp;<span class='foswikiUnvisited'><a id='pickparent' href='#ExampleCreateForm'>Pick from a list</a></span>
</p>
</div>
<div class="foswikiFormStep">
---+++ !!Use template:
<p>
<select name="templatetopic" class="foswikiSelect"><option value="">Default template</option></select> 
</p>
</div>
<div class="foswikiFormStep">
<p>
<input id="submit" type="submit" class="foswikiSubmit" value='Create this topic' />
</p>
</div>
</div>
</form>

   * The screen now changes to the edit mode. Just start entering some text, like when writing an e-mail.
   * Click =[Save]= to save the page. The edit mode disappears and you will be redirected to the topic you just created. *Congratulations - you are now actively participating in Foswiki!* And it was really simple, wasn't it?

Editing an existing topic is even more simple:
   * Click on the ==[Edit]== link - you will be redirected to the edit mode again.
   * Do some changes to your original text and save it. Done!

#FollowALink
---+++ 6.2 Create a topic following a link
Now we will proceed to the second option of creating a topic - following a link that refers to a topic that does not exist yet:
   * Click once more on the ==[Edit]== link.
   * Again, in the edit mode, type a WikiWord. A WikiWord is a word consisting of at least two capitalized words run together, so type e.g. =MySecondTopic=.
   * Save the topic and have a look at the [[WikiWord]] you just typed. You will notice a question mark behind the WikiWord. Once you finish creating your second topic, the question mark will disappear and word will be converted into a link. In fact, the word WikiWord is a link, too. Using the name of a topic is the easiest way to create links between two topics.
   * Now click on the question mark behind the WikiWord you just entered. You will be redirected to the edit mode, this time not for your first topic, but for the new one. This new (second) topic will be named after the link you created in the original topic. So if the WikiWord you typed in the original text was =MySecondTopic=, the new topic will be called =MySecondTopic=, too. %BR%
   <blockquote class="foswikiHelp">%H% If you were not redirected to the edit mode, but see some strange text (which is not yours) instead, it seems like the topic already existed :-) In this case, go back in your browser and type something different from =MySecondTopic=.</blockquote>

There are different ways of formatting text:
   1. *Using the WYSIWYG editor* - highlight and format text as you would do it in a normal text editor
   1. *Using TML shorthand* - TML (<strong>T</strong>opic <strong>M</strong>arkup <strong>L</strong>anguage) is a very simple markup language. For additional information on editing topics and formatting text with TML, have a look at WikiSyntax, TextFormattingRules and TopicsAndWebs.

---++ 7. Use your browser to upload files as page attachments...
 You can attach *any* type of file to a topic - documents, images, programs, whatever - where they can be opened, viewed, or downloaded.
 <blockquote class="foswikiHelp">%X% Your site administrator may have blocked some types of files (such as =.html=) from being attached for security reasons.</blockquote>
   * Attaching files is just like including a file with an e-mail. 
      1 Go once more to your sandbox topic and click on the ==[Attach]== icon.
      1 Click ==[Browse]== to find a file on your PC that you'd like to attach; enter an optional comment; leave everything else unchecked.
      1 Click ==[Upload file]==, then scroll to the end of the page to see the new attachment listing.
   * Do this again - this time, upload a GIF, JPG or PNG image file. 
      * Check the ==Properties:== box saying *Create a link to the attached file*. Once saving the topic, the image will show up at the bottom of the topic.
      * To move the image, edit the topic and place the last line (containing =%<nop>ATTACHURL%=) anywhere on the page.
   * If you have a GIF, JPG or PNG image of yourself, your cat, your sprawling family estate, why not upload it now to personalize your account page %WIKIUSERNAME%?

---++ 8. Get e-mail alerts whenever pages are changed...
%NOTIFYTOPIC% is a subscription service that automatically notifies you by e-mail when topics change in a Foswiki web. This is a convenience service - for many people, checking e-mail is easier than checking the Web. 
   * If you're using Foswiki to collaborate on a project, it's important to know when anyone on your team posts an update. If you're following a specific discussion, it's convenient to know when there's new input.
   * Alerts are e-mailed as links to individual topics that've been changed in a set period: each day, every hour, whatever is configured for your system.
   * It's strongly recommended that you try out the service by subscribing to each Foswiki web that's relevant to you. You can subscribe and unsubscribe instantly, on a per web basis using %NOTIFYTOPIC%.

That's it! You're now equipped with all the Foswiki essentials. You are ready to roll.

<blockquote class="foswikiHelp">%H% When first using Foswiki, it will probably seem strange to be able to change other people's postings - we're used to *separating* individual messages, with e-mail, message boards, non-Wiki collaboration platforms. _Don't worry about it._ You can't accidentally delete important stuff - you can always check previous versions, and restore them, if necessary, if you want to undo any changes. After a short while, it'll become second-nature and you'll expect it everywhere!</blockquote>

*Related Topics:* UserDocumentationCategory, TopicsAndWebs, WikiSyntax
%STOPINCLUDE%
This topic: System > WebHome > TwentyMinuteTutorial
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