From b383050c02130c6ec9121b84aeb630f832df3b25 Mon Sep 17 00:00:00 2001 From: ArthurClemens Date: Mon, 16 Aug 2004 05:39:41 +0000 Subject: [PATCH] none --- TWiki/PatternSkin.mdwn | 182 ++++++++++++++++++++++++++++++++++ TWiki/PatternSkinCss.mdwn | 175 ++++++++++++++++++++++++++++++++ TWiki/PatternSkinCustomization.mdwn | 114 +++++++++++++++++++++ TWiki/TWikiInstallationGuide.mdwn | 104 +++++++++++-------- TWiki/TWikiSystemRequirements.mdwn | 4 +- TWiki/TWikiTopics.mdwn | 2 +- TWiki/WebLeftBarCookbook.mdwn | 37 +++++++ TWiki/WebLeftBarPersonalTemplate.mdwn | 7 ++ TWiki/WebTopBar.mdwn | 9 ++ 9 files changed, 590 insertions(+), 44 deletions(-) create mode 100644 TWiki/PatternSkin.mdwn create mode 100644 TWiki/PatternSkinCss.mdwn create mode 100644 TWiki/PatternSkinCustomization.mdwn create mode 100644 TWiki/WebLeftBarCookbook.mdwn create mode 100644 TWiki/WebLeftBarPersonalTemplate.mdwn create mode 100644 TWiki/WebTopBar.mdwn diff --git a/TWiki/PatternSkin.mdwn b/TWiki/PatternSkin.mdwn new file mode 100644 index 0000000..74cf154 --- /dev/null +++ b/TWiki/PatternSkin.mdwn @@ -0,0 +1,182 @@ +# Pattern skin + +**PatternSkin is developed to provide a CSS based default look and feel for TWiki - flexible and [[W3C]]-compliant.** Its layout and color scheme are designed to provide a nice, clean and productive _editing environment_. For use in corporate or perhaps in personal websites it should be fairly easy to tune the looks or even create a PatternSkin-based new skin. + +
Page contents +
+ +## Screen Shot + +[Click for full screen image](http://www.dementia.org/twiki//view/patternskin_screenshot_full.png) + +## Supported browsers + +PatternSkin has been tested succesfully on the following browsers: + +- Windows + - Internet Explorer 6.0, 5.5 (note: Explorer 5.0 is **not** supported: will function but shows visual quirks) + - Mozilla/Firefox +- Mac OS X + - Safari 1.2 + - Mozilla/Firefox + +Not tested, but will probably work (let me know): + +- \*nix + - Mozilla/Firefox + +## Installation + +**Note:** You do not need to install anything on the browser to use this skin. The following instructions are for the administrator who installs the skin on the server where TWiki is running. + +**Note 2:** PatternSkin is included with TWiki by default. Use the following instructions only if you are upgrading PatternSkin. + +- Download the ZIP file from the Skin Home page (see below) +- Unzip **%TOPIC%.zip** in your twiki installation directory +- Test if installed: +- For skin activation see [[TWikiSkins]] + +### Troubleshooting + +If you have set the SKIN variable setting to `pattern` and you still don't see the layout as on the [screenshot](http://www.dementia.org/twiki//view/patternskin_screenshot_full.png), a few settings in may have been disabled. + +Check these variables here: + +- TWIKILAYOUTURL = %TWIKILAYOUTURL% +- TWIKISTYLEURL = %TWIKISTYLEURL% +- SKIN = %SKIN% + +If TWIKILAYOUTURL or TWIKISTYLEURL don't give a value or point to non-existing files, check in [[TWikiPreferences]] that the following variables do exist and that they are set to on: + + * %TWIKIWEB%.PatternSkin settings: + * Set TWIKILAYOUTURL = %PUBURL%/%TWIKIWEB%/PatternSkin/layout.css + * Set TWIKISTYLEURL = %PUBURL%/%TWIKIWEB%/PatternSkin/style.css + +If this still does not work, contact the administrator who installs skins. + +For further troubleshooting and feedback, go to TWiki:Plugins/PatternSkinDev. + +## Creating your own look + +It is easy to tune the look and feel of PatternSkin by changing the color and space (margin, padding) settings in the Style Sheet files. + +You may also choose to radically change the look and create a PatternSkin-based new skin. This is easier than to create a skin by writing new template files; you can concentrate on how things should look instead of what elements should get displayed. + +You can eiter: + +- Change the `layout.css` and `style.css` attachment files for this topic (upload updated versions) +- In [[TWikiPreferences]], point the variables `TWIKILAYOUTURL` and `TWIKISTYLEURL` to other attachments, perhaps in another topic (your new skin topic?) + +If you want to change colors and white space of screen elements, modify `style.css`.
If you want to change the positioning of screen elements, modify `layout.css`. + +See for practical details: [[PatternSkinCustomization]]
The CSS classes that PatternSkin uses are documented in [[PatternSkinCss]]. + +## Customization + +See: [[PatternSkinCustomization]] + +## Further reading + +- [[PatternSkinCustomization]] - Practical information on how to change the looks of PatternSkin +- [[PatternSkinCss]] - A reference to used CSS classes +- TWiki:Plugins/PatternSkinDev - Development page, bug reports, solutions from users + +## Skin Info + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Description: Provides a CSS based default look and feel for TWiki - flexible and [[Main/W3C]]-compliant
Screenshot: Click for full screen image
Base Name: pattern
Skin Author: TWiki:Main/ArthurClemens
Skin Version: 08 Aug 2004 (v1.000)
Download PatternSkin: PatternSkin.zip
Note: the CSS files in this topic may be more recent than the version in the zip file
Change History:  
14 Aug 2004: v.1.0.3 - Update to attach template, css fix to edit template
14 Aug 2004: v.1.0.2 - Fixes print template, table paddings in topics, minor changes to style.css
13 Aug 2004: v.1.0.1 - Updated /data/TWiki/WebLeftBarPersonalTemplate and style.css
08 Aug 2004: Initial version (v1.000)
Dependencies: [[TWiki/TablePlugin]]
Skin Home: http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%
Feedback: http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev
+ +## Related topics + +- TWiki:TWiki/TWikiCss +- TWiki:TWiki/WebBottomBar +- TWiki:TWiki/WebLeftBar +- TWiki:TWiki/WebLeftBarPersonalTemplate +- TWiki:TWiki/WebLeftBarCookbook +- TWiki:TWiki/WebTopBar + +See also [[Further reading|Main/TOPIC#Further_reading]] on this page. + +Other skins: + +- TWiki:TWiki/TWikiSkins +- TWiki:TWiki/TWikiSkinBrowser + +---- + +-- TWiki:Main/ArthurClemens - 15 Aug 2004 diff --git a/TWiki/PatternSkinCss.mdwn b/TWiki/PatternSkinCss.mdwn new file mode 100644 index 0000000..14db956 --- /dev/null +++ b/TWiki/PatternSkinCss.mdwn @@ -0,0 +1,175 @@ +# Css elements in PatternSkin + +This page is a reference for all CSS classes used in [[PatternSkin]]. + +
Page contents: +
+ +The PatternSkin stylesheet is divided in two files: + +- [layout.css](http://www.dementia.org/twiki//view/TWiki/PatternSkin/layout.css): positioning of block elements on the page +- [style.css](http://www.dementia.org/twiki//view/TWiki/PatternSkin/style.css): appearance of blocks and all other page elements + +If you want to learn how to create your own look or skin based on PatternSkin, read further in [[PatternSkin]]. + +## Naming conventions + +PatternSkin follows the naming conventions used in TWiki core code: all TWiki class names have the prefix `twiki`: twikiEditPage, twikiTopicAction, etcetera. ID names are not used, only class names, to allow multipe class names. See also: [[TWikiCss]]. + +## Namespaces + +PatternSkin uses namespaces for templates, by adding one (sometimes two - multiple) class names to the template's body tag. + +- The body tag in view.pattern.tmpl for instance has the class name "twikiViewPage": ``. All CSS elements specific to the view template thus can be defined as `.twikiViewPage .someClassName`. +- All templates that are _not_ the view template have the body class name "twikiNoViewPage". That makes it easy to give all of these pages a different layout in one sweep (smaller or wider margins for instance). Template edit.pattern.tmpl uses ``. + +### body class names + +- .twikiViewPage +- .twikiViewPage .twikiPrintPage +- .twikiNoViewPage +- .twikiNoViewPage .twikiEditPage +- .twikiNoViewPage .twikiAttachPage +- .twikiNoViewPage .twikiChangeFormPage +- .twikiNoViewPage .twikiDiffPage +- .twikiNoViewPage .twikiRenamePage +- .twikiSearchResultsPage + +## Layout classes + +- General + - .twikiLeft - a left floating element + - .twikiRight - a right floating element + - .twikiClear - to clean up either of these floats: put immediately after the containing block + - .twikiHidden - hidden element + +- TWiki block elements + - .twikiMiddleContainer - holder for twikiMain and twikiLeftbar + - .twikiLeftBar - left bar area + - .twikiLeftBarContents - used for left menu + - .twikiMain - holder of twikiToolbar, twikiTopic, twikiAttachments, etc. + - .twikiTopBar - top bar area + - .twikiBottomBar - bottom bar area + +- Layout adjustments on specific pages + - .twikiNoViewPage .twikiMain + - .twikiPrintPage .twikiMain + - .twikiPrintPage .twikiBottomBar + +## Style classes + +- .twikiMiddleContainer - holder for twikiMain and twikiLeftbar +- .twikiMain - holder of twikiToolbar, twikiTopic, twikiAttachments, etc) +- .twikiTopBar - top bar area +- .twikiTopBarContents - logo, go box +- .twikiLeftBar - left bar area +- .twikiWebIndicator - shows current Web name; background of color %WEBBGCOLOR% +- .twikiLeftBarContents - used for left menu (a bullet list) +- .twikiLeftBarPersonal - block of personal links (included topic %MAINWEB%.%USERNAME%LeftBar) +- .twikiBottomBar - bottom bar area +- .twikiBottomBarContents - copyright +- .twikiTopic +- .twikiAttachments - attachment table; used in template attachtables.tmpl +- .twikiForm - WebForm table; used in template attachtables.tmpl +- .twikiTopicAction - actions buttons at bottom of page; holder of table with buttons +- .twikiTopicActionSecondary - second layer above twikiTopicAction (for instance in Preview) +- .twikiTopicActionHelp - help text row +- .twikiCancelCol - table columns (td) for cancel button +- .twikiSubmitCol - table columns (td) for submit button +- .twikiAddCol - table columns (td) for additional button/link (for instance: "Move attachment") +- .twikiSeparator - separator character +- .twikiToc - topic contents (%TOC%) +- .twikiTocTitle - title of TOC (%TOC\{title="Contents:"\}%) +- .twikiTopicInfo - revision (%REVINFO%) and moved (%META\{"moved"\}%) info +- .twikiRevInfo - revision info (top and bottom of page) +- .twikiTopicFooter - used for breadcrumb (twikiHomePath) +- .twikiHomePath - breadcrumb +- .twikiToolBar - action buttons at top of topic (a bullet list), revision info +- .twikiPageNav - links "end of topic" and "to top" +- .twikiSearchBox - go box and current page in top bar +- .twikiHelp - help text +- .twikiBroadcastMessage - BROADCASTMESSAGE +- .twikiAlert - red +- .twikiGrayText - grayed out text, literally gray +- .twikiSmall - styled "small" +- .twikiNewLink - style of links to yet non-existent pages (not used) + +- Table class names (emitted from [[TablePlugin]]) + - .twikiSortedAscendingCol - sortable table column header that is sorted ascending (uses [[TablePlugin]]) + - .twikiSortedDescendingCol - ditto sorted descending + - .twikiFirstCol +- Other table class names + - .twikiVersatileTable - table used in various places (Attach, Rename, Changeform) + - .twikiVersatileTable .twikiMainCol - table column that is the most important part of the table + - .twikiVersatileTable .twikiOldCol - table column with 'old' appearance, for instance the old attachment or the old topic name + - .twikiVersatileTable .twikiHelpCol - table column with help texts + +- Search + - .twikiNew - emitted from Search.pm and Changes.pm with the text NEW + - .twikiSummary - summary text with search results + - .twikiSearchResults - the big block of all results + - .twikiSearchResultsHeader - top of block, styled with %WEBBGCOLOR% + - .twikiSearchResults .twikiTopRow - top of one result, with link, author, revision + - .twikiSearchResults .twikiBottomRow - result summary + - .twikiSearchResults .twikiAlert - used with "locked" text + - .twikiSearchResultCount - result count + - .twikiBookViewList - the big block of all results with book view option + +- Form elements + - .twikiCheckbox - styled checkbox + - .twikiRadioButton + - .twikiSubmit - submit button (in twikiTopicAction this is the darkest button; in twikiTopic it has a lighter color) + - .twikiButton - general button (in Rename/Delete: clear/select all checkboxes) + - .twikiSecondary - button next to submit button (same appearance as twikiButton) + - .twikiTertiary - button at far right (blue color) + - .twikiCancel - cancel button + - .twikiEditPage .twikiFormHolder - constrains the width of the textarea + - .twikiChangeFormButton - emitted from Form.pm, button to change the WebForm - styled as link + - .twikiEditForm - emitted from Form.pm, editable WebForm table + - .twikiEditFormTextField - emitted from Form.pm, input textfield in twikiEditForm + - .twikiSig - signature copy field + +- Preview + - .twikiPreviewPage .twikiPreviewArea - holder of previewed topic text + +- Attach + - .twikiAttachPage .twikiNotes - holder of help text + - .twikiAttachPage .twikiPrevious - attachment table of previous versions + +- Diff + - .twikiDiffPage .twikiDiffTable - block of revisions; emitted from RDiff.pm (also all diff classes below) + - .twikiDiffPage .twikiDiffDeletedHeader + - .twikiDiffPage .twikiDiffDeletedMarker + - .twikiDiffPage .twikiDiffDeletedText + - .twikiDiffPage .twikiDiffAddedHeader + - .twikiDiffPage .twikiDiffAddedMarker + - .twikiDiffPage .twikiDiffAddedText + - .twikiDiffPage th.twikiDiffChangedHeader + - .twikiDiffPage .twikiDiffChangedText + - .twikiDiffPage .twikiDiffUnchangedText + - .twikiDiffPage .twikiDiffLineNumberHeader + +## CSS tags emitted from TWiki core code + +See: [[TWikiCss]] + +## Layout per template + +### View template + +CSS layout in View template + +-- [[ArthurClemens]] - 08 Aug 2004 diff --git a/TWiki/PatternSkinCustomization.mdwn b/TWiki/PatternSkinCustomization.mdwn new file mode 100644 index 0000000..158db2b --- /dev/null +++ b/TWiki/PatternSkinCustomization.mdwn @@ -0,0 +1,114 @@ +# Customization of PatternSkin + +This page describes ways to change the layout, fonts and colors of [[PatternSkin]]. + +
Page contents: +
+ +## Screen parts + +The PatternSkin view template uses four screen parts: + +- The topic part - contains besides the topic content: action buttons, form table, attachment table, topic info +- Top bar - used for a logo, contains Go box +- Left bar - site and web navigation, contains a personal link block; may contain a Go box +- Bottom bar - copyright, disclaimer + +These parts are dynamically included topics: + +- Top bar: [[WebTopBar]] +- Left bar: included topic [[WebLeftBar]] (one WebLeftBar topic per web) + - Personal links block: Main.%USERNAME%LeftBar. Your own personal leftbar: Main.adminLeftBar +- Bottom bar: included topic [[WebBottomBar]] + +### Top bar + +The top bar is mainly used as branding space. To change the screen room for the logo, see below, [[Customizing the logo|Main/TOPIC#Customizing_the_logo]]. + +### Left bar + +The menu items are css-formatted bullet lists. So in [[WebLeftBar]] you write: + + * *Group* + * [[SomeTopic][Link 1]] + * [[AnotherTopic][Link 2]] + * [[ThirdTopic][Link 3]] + +The left bar may contain a Go box instead of the top bar. Use: + + * + +The personal left bar block is formatted like the rest of the left bar. + +### Bottom bar + +The bottom bar contains the copyright disclaimer, but may contain other information, perhaps a web list. + +## Customizing the logo + +The top bar is 60 pixels high, and has a padding of 5 pixels on top, bottom and left, so the logo should be 50 pixels high. If your logo image has a different size, you can either alter the padding in `style.css` (.twikiTopBarContents) or change the top bar height in `layout.css` (look for the comment _setting the height of the top bar_). + +You can also choose to set a background image for the top bar. In `style.css`, add this to .twikiTopBar: + + background-position:top left; + background-attachment:fixed; + background-repeat:no-repeat; + background-image:url(http://absolute_path_to_your_image); + +and set the correct image file path. + +## Fonts + +### Font style + +Font styles are defined in `style.css` in these places: + + html body { + font-family:"Lucida Grande", verdana, lucida, helvetica, sans-serif; + } + h1, h2, h3, h4, h5, h6 { + font-family:"Lucida Grande", helvetica, lucida, verdana, sans-serif; + } + textarea { + font-family:monospace; + } + input, select { + font-family:verdana,arial,sans-serif; + } + .twikiSeparator { + font-family:Arial,sans-serif; + } + .twikiEditPage .twikiSig input { + font-family:monospace; + } + +### Font size + +Font sizes in PatternSkin are scalable. This means that even on Windows Explorer, the text in the browser can scale with the user settings (in contrast to many sites where texts have a fixes pixel size, these cannot be changed by the user). + +Scalable text is a big accessibility asset. If you notwithstanding want to have a fixed font, or if you want to set the default size smaller or bigger, the easiest way is to make a new entry for body, below the 2 other entries: + + html body { + ... (keep) + } + html>body { + ... (keep) + } + html body { + font-size:11px; + } + +-- [[ArthurClemens]] - 15 Aug 2004 diff --git a/TWiki/TWikiInstallationGuide.mdwn b/TWiki/TWikiInstallationGuide.mdwn index b317cca..bad1b85 100644 --- a/TWiki/TWikiInstallationGuide.mdwn +++ b/TWiki/TWikiInstallationGuide.mdwn @@ -7,13 +7,15 @@
  • Step 2: Set File Permissions
  • -
  • Step 3: Set the Main Configuration File
  • -
  • Step 4: Configure Site-Wide Email Preferences
  • -
  • Step 5: Finish Up from Your Browser
  • +
  • Step 3: Edit the Configuration Files
  • +
  • Step 4: Internationalisation Setup (Optional)
  • +
  • Step 5: Configure Site-Wide Email Preferences
  • +
  • Step 6: Finish Up from Your Browser
  • Additional Server-Level Options
  • TWiki File System Info
  • @@ -24,7 +26,7 @@ # TWiki Installation Guide -_Installation instructions for the TWiki 01-Feb-2003 production release._ +_Installation instructions for the TWiki 01-Sep-2004 production release._ _If you are reading this on your own TWiki installation, please get the latest installation guide (TWiki:TWiki.TWikiInstallationGuide), as this often has important updates to resolve installation issues._ @@ -35,13 +37,13 @@ These installation steps are based on the **Apache** web server on **Linux**. TW - For MacOS X, check TWiki:Codev/TWikiOnMacOSX. - To install TWiki on SourceForge, for use on a software development project, read TWiki:Codev/TWikiOnSourceForge - For other platforms, see TWiki:Codev/TWikiOn, and search the TWiki:Codev and TWiki:Support webs for other installation notes. -- If you need **_really urgent_** help, try the TWiki:Codev/TWikiIRC channel. +- If you need help, ask a question in the TWiki:Support web ## Standard Installation -Request and download the TWiki 01-Feb-2003 distribution in Unix ZIP format from . Please review the [[AdminSkillsAssumptions]] before you install TWiki. +Download the TWiki 01-Sep-2004 distribution in Unix ZIP format from . Please review the [[AdminSkillsAssumptions]] before you install TWiki. ### Step 1: Create & Configure the Directories @@ -74,7 +76,7 @@ Request and download the TWiki 01-Feb-2003 distribution in Unix ZIP format from > deny from all > -- Restart Apache by `/etc/rc.d/rc5.d/S85httpd restart` . +- Restart Apache by `service httpd restart` (or as appropriate to your flavor of UNIX or Linux). - Test that the `twiki/bin` directory is CGI-enabled by trying visiting it in your browser: - Enter the URL for the `bin` directory, `http://yourdomain.com/twiki/bin/`. - Your settings are OK if you get a message like `"Forbidden. You don't have permission to access /twiki/bin/ on this server"`. @@ -137,39 +139,37 @@ To install TWiki on a system where you don't have Unix/Linux root (administrator > > -If you are not able to create the `twiki/lib` directory at the same level as the `twiki/bin` directory (e.g. because CGI `bin` directories can't be under your home directory and you don't have root access), you can create this directory elsewhere and edit the `setlib.cfg` file in the `bin` directory: - -
    -	 # -------------- Change these settings if required
    -
    -	 $twikiLibPath = '/some/other/path/lib';	# Path to lib directory containing TWiki.pm
    -
    -
    - -You can also edit `$localPerlLibPath` in the `setlib.cfg` file if you are not root and need to install additional CPAN modules, but can't update the main Perl installation files on the server. Just set this variable to the full pathname to your local lib directory, typically under your home directory. +**_Note:_** Don't worry if you are not able to put the `twiki/lib` directory at the same level as the `twiki/bin` directory (e.g. because CGI `bin` directories can't be under your home directory and you don't have root access). You can create this directory elsewhere and configure the `/twiki/bin/setlib.cfg` file (done in Step 3) ### Step 2: Set File Permissions - Make sure Perl 5 and the Perl CGI library are installed on your system. The default location of Perl is `/usr/bin/perl`. If it's elsewhere, change the path to Perl in the first line of each script in the `twiki/bin` directory, or create a symbolic link from `/usr/bin/perl`. - - **IMPORTANT:** On ISP-hosted accounts (and some intranet servers), Perl CGI scripts may require a `.cgi` extension to run. Some systems need `.pl`, the regular Perl extension. Rename all `twiki/bin` scripts if necessary. + - **IMPORTANT:** + - On ISP-hosted accounts (and some intranet servers), Perl CGI scripts may require a `.cgi` extension to run. Some systems need `.pl`, the regular Perl extension. Rename all `twiki/bin` scripts if necessary. + - Alternatively, you might try creating a file `twiki/bin/.htaccess` that contains the single line `SetHandler cgi-script`, which tells Apache to treat all files in this directory as CGI scripts. - Set the file permission of all Perl scripts in the `twiki/bin` directory as executable to `-rwxr-xr-x` (755). - To be able to edit the Perl scripts and `.tmpl` files it is necessary to `chown` and `chgrp -R twiki` so all the files have the owner you want. - %H% This Guide assumes user `nobody` ownership for all files manipulated by the CGI scripts (executed by the Web server), and user `twiki` for all other files. You can: - replace `nobody` with another user if your server executes scripts under a different name (ex: default for Debian is `www-data`). - %T% **HINT:** Run the `testenv` script from your browser: `http://yourdomain.com/twiki/bin/testenv`. It will show you the user name of the CGI scripts, a table listing all CGI environment variables, and a test of your `twiki/lib/TWiki.cfg` configuration file (you'll configure that in a minute). - replace user `twiki` with your own username -- Set the permission of all files below `twiki/data` so that they are writable by user `nobody`. A simple way is to `chmod` them to `-rw-rw-r--` (664) and to `chown` them to `nobody`. -- Set the permission of the `twiki/data` directory and its subdirectories so that files in there are writable by user `nobody`. A simple way is to chmod them to `drwxrwxr-x` (775) and to `chown` them to `nobody`. -- Set the permission of the `twiki/pub` directory and all its subdirectories so that files in there are writable by user `nobody`. A simple way is to `chmod` them to `drwxrwxr-x` (775) and to `chown` them to `nobody`. -- %H% The `twiki/data/*/*.txt,v` RCS repository files in the installation package are locked by user `nobody`. If your CGI scripts are **_not_** running as user `nobody`, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, such as `www-data`, or delete them all - new files will be automatically created the first time each topic is edited. A simple way to change ownership is with a search-and-replace in all files; for example, using Perl (type this carefully!): - -> cd twiki/data -> perl -pi~ -e 'NR <= 10 && s/nobody:/www-data:/ ' */*,v - -### Step 3: Set the Main Configuration File - +- Set permissions manually. + - Set the permission of all **files** below `twiki/data` so that they are writable by user `nobody`. A simple way is to `chmod` them to `-rw-rw-r--` (664) and to `chown` them to `nobody`. + - Set the permission of the `twiki/data` **directory** and its **subdirectories** so that files in there are writable by user `nobody`. A simple way is to chmod them to `drwxrwxr-x` (775) and to `chown` them to `nobody`. + - Set the permission of the `twiki/pub` directory and all its subdirectories so that files in there are writable by user `nobody`. A simple way is to `chmod` them to `drwxrwxr-x` (775) and to `chown` them to `nobody`. + - %H% The `twiki/data/*/*.txt,v` RCS repository files in the installation package are locked by user `nobody`. If your CGI scripts are **_not_** running as user `nobody`, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, such as `www-data`, or delete them all - new files will be automatically created the first time each topic is edited. You have two options to change ownership of the RCS lock user: + - Run the `testenv` script from your browser; in the %BROWN% **Fix** %ENDCOLOR% line you can relock all the rcs files + - Alternatively, run this in your shell: %BR% `cd twiki/data` %BR% `find . -name *.v~ -exec perl -pi~ -e '$. <= 10 && s/nobody:/www-data:/ ' {} ;` + +### Step 3: Edit the Configuration Files + +- Edit the file `/twiki/bin/setlib.cfg` + - Set `$twikiLibPath` to the absolute file path of your `/twiki/lib` as seen by the web server. + - %X% **_Attention:_** Do **not** leave it as a relative `"../lib"` path or Plugins might fail to initialize properly + - You can also edit `$localPerlLibPath` if you are not root and need to install additional CPAN modules, but can't update the main Perl installation files on the server. Just set this variable to the full pathname to your local lib directory, typically under your home directory. + - %X% **_Attention:_** If you are running TWiki on Apache 2.0 on Unix you might experience cgi scripts to hang forever. This is a known Apache 2.0 bug. See details and woraround in the `setlib.cfg` file. - Edit the file `twiki/lib/TWiki.cfg`, setting the variables to your needs. - Set the file extension in the `$scriptSuffix` variable to `cgi` or `pl` if required. - RCS - revision control system to store revision of topics and attachments. You can use RCS executables or a version of RCS written in Perl, note that as the time of writing (Apr 2002) the Perl version has not been widely tested, so if you want to put up a live site the RCS executables are recommended. @@ -179,7 +179,31 @@ You can also edit `$localPerlLibPath` in the `setlib.cfg` file if you are not ro - **Security issue:** Directories `twiki/data` , `twiki/templates` and all their subdirectories should be set so that they are **_not_** visible through URLs. (Alternatively, move the directories to a place where they are not visible, and change the variables in `twiki/lib/TWiki.cfg` accordingly) - Test your settings by running the `testenv` script from your browser: `http://yourdomain.com/twiki/bin/testenv`. Check if your `twiki/lib/TWiki.cfg` configuration file settings are correct. -### Step 4: Configure Site-Wide Email Preferences +### Step 4: Internationalisation Setup (Optional) + +By default, TWiki is configured to support US ASCII letters (no accents) in [[WikiWords]], and ISO-8859-1 (Western European) characters in page contents. If that's OK for you, skip this step. + +If your Wiki will be used by non-English speakers, TWiki can be configured for Internationalisation ('I' followed by 18 letters, then 'N', or _I18N_). Specifically, TWiki will support suitable accented characters in [[WikiWords]] (as well as languages such as Japanese or Chinese in which [[WikiWords]] do not apply), and to support virtually any character set in the contents of pages. **_NOTE:_** _TWiki does not currently support UTF-8, so you are advised **not** to use this - however, improved UTF-8 support is [under development](http://twiki.org/cgi-bin/view/Codev/ProposedUTF8SupportForI18N)._ + +To configure internationalisation suppport: + +1. Edit the `TWiki.cfg` file's Internationalisation section to set the `$useLocale` parameter to `1`. TWiki will now use the [[I18N]] parameters set in the rest of this section. +2. Type the Unix/Linux command `locale -a` to find a suitable 'locale' for your use of TWiki. A locale that includes a dot followed by a character set is recommended, e.g. `pl_PL.ISO-8859-2` for Poland. Consult your system administrator if you are not sure which locale to use. +3. In `TWiki.cfg`, set the `$siteLocale` parameter to your chosen locale, e.g. `pl_PL.ISO-8859-2` for Poland. +4. Check your setup using `testenv` (download the latest `testenv` from TWiki:Support/SupportGuidelines if possible) - this provides some diagnostics for [[I18N]] setup, and in particular checks that your locale can be used successfully. +5. If you are using Internet Explorer or Opera, configure your browser to not send URLs encoded with UTF-8 + - Internet Explorer 5.0 or higher: in _Tools | Options | Advanced_, uncheck 'always send URLs as UTF-8', then close all IE windows and restart IE. + - Opera 6.x or higher: in _Preferences | Network | International Web Addresses_, uncheck 'encode all addresses with UTF-8'. + - **_NOTE:_** _If this configuration change is not acceptable, consider installing a TWiki beta release (19 Jan 2004 or later), which fully supports UTF-8 URLs._ +6. Try out your TWiki by creating pages in the Sandbox web that use international characters in [[WikiWords]] and checking that searching, [[WebIndex]], Ref-By and other features are working OK. + +If international characters in [[WikiWords]] do not seem to work, and you are on Perl 5.6 or higher, you may need to set the `TWiki.cfg` parameter `$localeRegexes` to 0 - this disables some features but enables TWiki to work even if your system has locales that do not work. Then, set the `$upperNational` and `$lowerNational` parameters to the valid upper and lower case accented letters for your locale. + +- **_NOTE:_** _You will need to do the above workaround for Windows based servers (whether using Cygwin or ActiveState Perl), since Perl locales are not working on Windows as of Feb 2004._ + +If international characters in [[WikiWords]] aren't working, and you are on Perl 5.005 with working locales, keep `$useLocale` set to 1 and set `$localeRegexes` to 0, then set `$upperNational` and `$lowerNational` - if `testenv` generates the lists of characters for you, your locales are working so there is no need to set `$localeRegexes` to 0 in this case. See the comments in `TWiki.cfg` for more information. + +### Step 5: Configure Site-Wide Email Preferences - Edit the [[TWikiPreferences]] topic in the TWiki web (by pointing your browser to http://yourdomain.com/twiki/bin/view/TWiki/TWikiPreferences) to set the `WIKIWEBMASTER` email address, and other email settings required for registration and [[WebChangesAlert]] to work: - `WIKIWEBMASTER` should be set to the email address of the TWiki administrator @@ -188,17 +212,17 @@ You can also edit `$localPerlLibPath` in the `setlib.cfg` file if you are not ro - You may want to set up other [[TWikiPreferences]] later on. - To enable the [[WebChangesAlerts]] (email notifications) you need to read about cron in the topic [[TWikiSiteTools]]. -### Step 5: Finish Up from Your Browser +### Step 6: Finish Up from Your Browser - Point your Web browser at `http://yourdomain.com/twiki/bin/view` and start TWiki-ing away! - %T% Or, point to `http://yourdomain.com/twiki/` to get the pre-TWiki `index.html` page, with a link to the `view` script. Customize this page if you want a public intro screen with a login link, instead of immediately calling up the .htaccess login dialog by going directly to `view`. - Edit the [[WebPreferences]] topic in each web, if necessary: set individual `WEBCOPYRIGHT` messages, and other preferences. -- Enable email notification of topic changes, [[TWikiSiteTools]] has more. +- Enable email notification of topic changes - [[TWikiSiteTools]] has more. - Edit the [[WebNotify]] topic in all webs and add the users you want to notify. - Add the TWiki:Main/PoweredByTWikiLogo to your [[Main.WebHome|Main/WebHome]] topic. - You can add new `%VARIABLES%`. Define site-level variables in the [[TWikiPreferences]] topic. See also: [[TWikiVariables]]. -That's it for the standard virgin installation of TWiki. Read on for server-level customization options. +That's it for the standard installation of TWiki. Read on for server-level customization options. ## Additional Server-Level Options @@ -214,10 +238,11 @@ With your new TWiki installation up and running, you can manage most aspects of - %H% The browser should ask for login name and password when you click on the Edit link. In case `.htaccess` does not have the desired effect, you need to enable it: Add "AllowOverride All" to the Directory [[3]](http://httpd.apache.org/docs/mod/core.html#directory) section of `access.conf` for your `twiki/bin` directory. - **This applies only if you have root access:** on hosted accounts, you shouldn't have this problem - otherwise, email tech support. - %X% **NOTE:** In the TWiki distribution package, the `twiki/data/.htpasswd.txt` file contains several TWiki core team user accounts and a guest user account. You probably want to remove those accounts by deleting the entries in `.htpasswd`. Do not remove the guest user if you want to allow guest logins. - 2. **Copy** the [[TWikiRegistrationPub]] topic to [[TWikiRegistration]], overwriting old version of TWikiRegistration. Do that by either editing the topics in theTWiki web, or by renaming the `.txt` and `.txt,v` files in the `twiki/data/TWiki` directory. + 2. TWiki now supports several Password file format/encoding methods for Apache. Once you know what method is used by your Appache server, you can configure TWiki to create compatible .htpasswd entries by editing the `$htpasswdFormatFamily`, `$htpasswdEncoding` and `$htpasswdFilename` in the TWiki.cfg file. The supported options are htpasswd:plain, htpasswd:crypt, htpasswd:sha1, htdigest:md5 + 3. **Copy** the [[TWikiRegistrationPub]] topic to [[TWikiRegistration]], overwriting old version of TWikiRegistration. Do that by either editing the topics in theTWiki web, or by renaming the `.txt` and `.txt,v` files in the `twiki/data/TWiki` directory. - Customization: - You can customize the registration form by deleting or adding input tags. The `name=""` parameter of the input tags must start with: `"Twk0..."` (if this is an optional entry), or `"Twk1..."` (if this is a required entry). This ensures that the fields are carried over into the user home page correctly. - - You can customize the default user home page in [[NewUserTemplate]]. + - You can customize the default user home page in [[NewUserTemplate]]. The same variables get expanded as in the [[template topics|Main/TWikiTemplates#Template_Topics]] - Register yourself in the [[TWikiRegistration]] topic. - %X% **NOTE:** When a user registers, a new line with the username and encrypted password is added to the `data/.htpasswd` file. The `.htpasswd` file that comes with the TWiki installation includes user accounts for TWiki core team members that are used for testing on TWiki.org. You can edit the file and delete those lines. - Create a new topic to check if authentication works. @@ -225,17 +250,14 @@ With your new TWiki installation up and running, you can manage most aspects of - Edit the [[TWikiPreferences]] topic in the TWiki:TWiki web to set access privileges. - Edit the [[WebPreferences]] topic in each web, if necessary: set access priviliges. -That's it for a basic new web set-up! - -Optionally, you can also: +### WYSIWYG Editor -- Create custom web-specific templates in a new `twiki/templates/Someweb` directory (otherwise, templates are inherited from `twiki/templates`). -- Add [[TWikiForms]] for form-based page input that's stored separately from the main free-form topic text. +At this time, TWiki does not ship with an "what you see is what you get" editor. TWiki:Codev/IntegrateHtmlAreaEditor describes how to integrate an HTML editor. %X% **NOTE:** User home topics are located in the %WIKITOOLNAME%.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to %WIKITOOLNAME%.Main web, using a `Main.UserName` or `%MAINWEB%.UserName` format. (The `%MAINWEB%` variable is an advantage if you ever change the Main web name, but the standard `Main.UserName` is easier for users to enter, which is the bottom line! ## TWiki File System Info -See [[Appendix A: TWiki File System|Main/AppendixFileSystem]] for an installed system snapshot and descriptions of all files in the TWiki 01-Sep-2001 distribution. +See [[Appendix A: TWiki File System|Main/AppendixFileSystem]] for an installed system snapshot and descriptions of all files in the TWiki 01-Sep-2004 distribution. --- [[PeterThoeny]] - 03 Jun 2003
    -- [[MikeMannix]] - 16 May 2002 +-- TWiki:Main/PeterThoeny - 15 Aug 2004 %BR% -- TWiki:Main/MikeMannix - 16 May 2002 diff --git a/TWiki/TWikiSystemRequirements.mdwn b/TWiki/TWikiSystemRequirements.mdwn index 041a94c..81b8009 100644 --- a/TWiki/TWikiSystemRequirements.mdwn +++ b/TWiki/TWikiSystemRequirements.mdwn @@ -11,7 +11,7 @@ # TWiki System Requirements -_Server and client requirements for TWiki 01-Feb-2003_ +_Server and client requirements for TWiki 01-Sep-2004_ Low client and server requirements are core features that keep TWiki widely deployable, particularly across a range of browser platforms and versions. @@ -66,7 +66,7 @@ The TWiki [[standard installation|Main/TWikiInstallationGuide]] has extremely lo - generates XHTML 1.0 pages that are compatible with HTML 3.2 - minimal use of JavaScript in the user interface (degrades gracefully) - no cookies -- no CSS +- no CSS (if the [[ClassicSkin]] is used) You can easily add functionality, by customizing [[TWikiTemplates]], for one, while tailoring the browser requirements to your situation. diff --git a/TWiki/TWikiTopics.mdwn b/TWiki/TWikiTopics.mdwn index 032795d..1800da6 100644 --- a/TWiki/TWikiTopics.mdwn +++ b/TWiki/TWikiTopics.mdwn @@ -152,4 +152,4 @@ RCS revision control automatically saves all topic changes. To look at earlier v See: [[ManagingTopics|Main/TWikiDocumentation#Managing_Topics]] for more details. --- TWiki:MikeMannix - 22 May 2002 %BR% -- TWiki::Main.GrantBow - 17 Jan 2003 %BR% +-- TWiki:MikeMannix - 22 May 2002 %BR% -- TWiki:Main.GrantBow - 17 Jan 2003 %BR% diff --git a/TWiki/WebLeftBarCookbook.mdwn b/TWiki/WebLeftBarCookbook.mdwn new file mode 100644 index 0000000..a67c362 --- /dev/null +++ b/TWiki/WebLeftBarCookbook.mdwn @@ -0,0 +1,37 @@ +# WebLeftBar Cookbook + +**Instructions and tips how to use [[WebLeftBarPersonalTemplate]]**. + +WebLeftBarPersonalTemplate is a topic template to create a personal left bar block for each user. The personal topic, <user>LeftBar is included in [[WebLeftBar]], the left menu used in [[PatternSkin]]. It is only visible to you. You can put links to frequently visited topics there, or a dynamically generated list of topics. + +Each link is an item in a bullet list. So it can look like this: + +- **My links** + - [[WebHome]] + - [[WebIndex]] + - [[WebChanges]] + +(but with _your_ personal topics). + +The list is formatted with CSS, and the bullets themselves are not displayed, and also indents are flattened. To get an idea of the actual look, see the list above formatted as in the left bar (you need to have [[PatternSkin]] set to on): + +
    +
    +
    +
      +
    • My links
        +
      • [[Main/WebHome]]
      • +
      • [[Main/WebIndex]]
      • +
      • [[Main/WebChanges]]
      • +
      +
    • +
    +
    +
    +
    + +By default the <user>LeftBar topic has an edit link. In case you loose the edit link line of text, here's a copy: + + + +-- [[ArthurClemens]] - 15 Aug 2004 diff --git a/TWiki/WebLeftBarPersonalTemplate.mdwn b/TWiki/WebLeftBarPersonalTemplate.mdwn new file mode 100644 index 0000000..8761151 --- /dev/null +++ b/TWiki/WebLeftBarPersonalTemplate.mdwn @@ -0,0 +1,7 @@ +Customise this topic; samples and ideas available at TWiki:TWiki.WebLeftBarCookbook. + +- **My links** +- [[My home page|Main/Admin]] +- [![Show me topics of interest](http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/stargold.gif)](http://www.dementia.org/twiki//search/Codev/?search=InterestedParties.*admin®ex=on) + +
    edit
    diff --git a/TWiki/WebTopBar.mdwn b/TWiki/WebTopBar.mdwn new file mode 100644 index 0000000..e6e1323 --- /dev/null +++ b/TWiki/WebTopBar.mdwn @@ -0,0 +1,9 @@ +
    Home
    +
    + + + + +
    +
    +
    -- 1.9.4