buildrelease
authorTWikiContributor <TWikiContributor>
Tue, 22 Jan 2008 03:21:37 +0000 (03:21 +0000)
committerTWikiContributor <TWikiContributor>
Tue, 22 Jan 2008 03:21:37 +0000 (03:21 +0000)
368 files changed:
Main/ClassicSkinUserViewTemplate.mdwn [new file with mode: 0644]
Main/TWikiAdminUser.mdwn [new file with mode: 0644]
Main/WebCreateNewTopic.mdwn [new file with mode: 0644]
Main/WebStatistics.mdwn
TWiki/ATasteOfTWiki.mdwn
TWiki/AccessKeys.mdwn
TWiki/AdminSkillsAssumptions.mdwn
TWiki/AdminToolsCategory.mdwn
TWiki/AppendixEncodeURLsWithUTF8.mdwn
TWiki/BehaviourContrib.mdwn
TWiki/BulkRegistration.mdwn
TWiki/BulkResetPassword.mdwn
TWiki/CGISessionDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionDriverDBIDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionDriverDb_fileDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionDriverDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionDriverFileDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionDriverMysqlDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionDriverPostgresqlDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionDriverSqliteDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionErrorHandlerDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionIDIncrDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionIDMd5DotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionSerializeDefaultDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionSerializeFreezethawDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionSerializeJsonDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionSerializeStorableDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionSerializeYamlDotPm.mdwn [new file with mode: 0644]
TWiki/CGISessionTutorialDotPm.mdwn [new file with mode: 0644]
TWiki/ChangeEmailAddress.mdwn
TWiki/ChangePassword.mdwn
TWiki/ClassicSkin.mdwn
TWiki/CommentPlugin.mdwn
TWiki/CommentPluginExamples.mdwn
TWiki/CommentPluginTemplate.mdwn
TWiki/EditDoesNotIncreaseTheRevision.mdwn
TWiki/EditTablePlugin.mdwn
TWiki/EmptyPlugin.mdwn
TWiki/FileAttachment.mdwn
TWiki/ForceNewRevision.mdwn
TWiki/FormatTokens.mdwn [new file with mode: 0644]
TWiki/FormattedSearch.mdwn
TWiki/GoBox.mdwn
TWiki/GoodStyle.mdwn
TWiki/HierarchicalNavigation.mdwn
TWiki/IfStatements.mdwn
TWiki/IncludeTopicsAndWebPages.mdwn
TWiki/InstalledPlugins.mdwn
TWiki/InstantEnhancements.mdwn
TWiki/InterWikis.mdwn
TWiki/InterwikiPlugin.mdwn
TWiki/JSCalendarContrib.mdwn
TWiki/JSCalendarContribInline.mdwn [new file with mode: 0644]
TWiki/LanguageSelector.mdwn
TWiki/MailerContrib.mdwn
TWiki/MainFeatures.mdwn
TWiki/ManagingTopics.mdwn
TWiki/ManagingUsers.mdwn
TWiki/ManagingWebs.mdwn
TWiki/MonitorDotPm.mdwn [new file with mode: 0644]
TWiki/PatternSkin.mdwn
TWiki/PatternSkinColorSettings.mdwn
TWiki/PatternSkinCss.mdwn
TWiki/PatternSkinCssCookbook.mdwn
TWiki/PatternSkinCssCookbookCenterPage.mdwn
TWiki/PatternSkinCssCookbookCenterPageBorder.mdwn
TWiki/PatternSkinCssCookbookEditTableStyle.mdwn
TWiki/PatternSkinCssCookbookFonts.mdwn
TWiki/PatternSkinCssCookbookNoLeftBar.mdwn
TWiki/PatternSkinCssCookbookNoTopBar.mdwn
TWiki/PatternSkinCustomization.mdwn
TWiki/PatternSkinElements.mdwn
TWiki/PatternSkinGraphics.mdwn [new file with mode: 0644]
TWiki/PatternSkinWebCreateNewTopicTemplate.mdwn [new file with mode: 0644]
TWiki/PlainSkin.mdwn
TWiki/PreferencesPlugin.mdwn
TWiki/PrintSkin.mdwn
TWiki/QuerySearch.mdwn [new file with mode: 0644]
TWiki/RegistrationApprovals.mdwn
TWiki/RenameWeb.mdwn
TWiki/RenderListPlugin.mdwn
TWiki/ResetPassword.mdwn
TWiki/SearchPatternCookbook.mdwn
TWiki/SiteMap.mdwn
TWiki/SitePermissions.mdwn
TWiki/SlideShowPlugin.mdwn
TWiki/SmiliesPlugin.mdwn
TWiki/SourceCode.mdwn
TWiki/SpreadSheetPlugin.mdwn
TWiki/TWikiAccessControl.mdwn
TWiki/TWikiAccessControlExceptionDotPm.mdwn
TWiki/TWikiAccessDotPm.mdwn
TWiki/TWikiAddOns.mdwn
TWiki/TWikiAggregateIteratorDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiAttachDotPm.mdwn
TWiki/TWikiAttrsDotPm.mdwn
TWiki/TWikiCompatibilityDotPm.mdwn
TWiki/TWikiContribs.mdwn
TWiki/TWikiContributor.mdwn
TWiki/TWikiCss.mdwn
TWiki/TWikiDocGraphics.mdwn
TWiki/TWikiDocumentation.mdwn
TWiki/TWikiDotPm.mdwn
TWiki/TWikiEditingShorthand.mdwn
TWiki/TWikiFormDotPm.mdwn
TWiki/TWikiFormFieldDefinitionDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiFormListFieldDefinitionDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiFormSelectDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiForms.mdwn
TWiki/TWikiFuncDotPm.mdwn
TWiki/TWikiGlossary.mdwn
TWiki/TWikiHistory.mdwn
TWiki/TWikiI18NDotPm.mdwn
TWiki/TWikiIfNodeDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiIfParserDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiInfixErrorDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiInfixNodeDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiInfixParserDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiInstallationGuide.mdwn
TWiki/TWikiJavascripts.mdwn
TWiki/TWikiLineIteratorDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiListIteratorDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiLoginManagerApacheLoginDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiLoginManagerDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiLoginManagerTemplateLoginDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiLogos.mdwn
TWiki/TWikiMetaData.mdwn
TWiki/TWikiMetaDotPm.mdwn
TWiki/TWikiNetDotPm.mdwn
TWiki/TWikiNetHTTPResponseDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiOopsExceptionDotPm.mdwn
TWiki/TWikiPluginDotPm.mdwn
TWiki/TWikiPlugins.mdwn
TWiki/TWikiPluginsDotPm.mdwn
TWiki/TWikiPreferences.mdwn
TWiki/TWikiPreferencesForm.mdwn
TWiki/TWikiPrefsDotPm.mdwn
TWiki/TWikiPrefsPrefsCacheDotPm.mdwn
TWiki/TWikiQueryHoistREsDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiQueryNodeDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiQueryParserDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiRegistration.mdwn
TWiki/TWikiReleaseNotes04x00.mdwn
TWiki/TWikiReleaseNotes04x01.mdwn
TWiki/TWikiReleaseNotes04x02.mdwn [new file with mode: 0644]
TWiki/TWikiRenderDotPm.mdwn
TWiki/TWikiSandboxDotPm.mdwn
TWiki/TWikiScripts.mdwn
TWiki/TWikiSearchDotPm.mdwn
TWiki/TWikiSite.mdwn
TWiki/TWikiSiteTools.mdwn
TWiki/TWikiSkins.mdwn
TWiki/TWikiStoreDotPm.mdwn
TWiki/TWikiStoreQueryAlgorithmsBruteForceDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiStoreRcsFileDotPm.mdwn
TWiki/TWikiStoreRcsLiteDotPm.mdwn
TWiki/TWikiStoreRcsWrapDotPm.mdwn
TWiki/TWikiStoreSearchAlgorithmsForkingDotPm.mdwn
TWiki/TWikiSystemRequirements.mdwn
TWiki/TWikiTemplates.mdwn
TWiki/TWikiTemplatesDotPm.mdwn
TWiki/TWikiTimeDotPm.mdwn
TWiki/TWikiTip011.mdwn
TWiki/TWikiTip028.mdwn
TWiki/TWikiTip029.mdwn
TWiki/TWikiTipsOfTheDay.mdwn
TWiki/TWikiTipsOfTheDayAddNew.mdwn
TWiki/TWikiTipsOfTheDayAdmin.mdwn
TWiki/TWikiTipsOfTheDayTemplate.mdwn
TWiki/TWikiTopics.mdwn
TWiki/TWikiTutorial.mdwn
TWiki/TWikiUIEditDotPm.mdwn
TWiki/TWikiUIManageDotPm.mdwn
TWiki/TWikiUIOopsDotPm.mdwn
TWiki/TWikiUIRDiffDotPm.mdwn
TWiki/TWikiUIRegisterDotPm.mdwn
TWiki/TWikiUISaveDotPm.mdwn
TWiki/TWikiUISearchDotPm.mdwn
TWiki/TWikiUIStatisticsDotPm.mdwn
TWiki/TWikiUIUploadDotPm.mdwn
TWiki/TWikiUIViewDotPm.mdwn
TWiki/TWikiUpgradeGuide.mdwn
TWiki/TWikiUserAuthentication.mdwn
TWiki/TWikiUserMappingContrib.mdwn [new file with mode: 0644]
TWiki/TWikiUserMappingDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiUsersApacheHtpasswdUserDotPm.mdwn
TWiki/TWikiUsersDotPm.mdwn
TWiki/TWikiUsersHtPasswdUserDotPm.mdwn [new file with mode: 0644]
TWiki/TWikiUsersPasswordDotPm.mdwn
TWiki/TWikiUsersTemplate.mdwn [new file with mode: 0644]
TWiki/TWikiVariables.mdwn
TWiki/TWikiVariablesQuickStart.mdwn
TWiki/TWikiWebsTable.mdwn
TWiki/TablePlugin.mdwn
TWiki/TemplateWeb.mdwn
TWiki/TextFormattingFAQ.mdwn
TWiki/TextFormattingRules.mdwn
TWiki/TimeSpecifications.mdwn [new file with mode: 0644]
TWiki/TinyMCEPlugin.mdwn [new file with mode: 0644]
TWiki/TinyMCEQuickHelp.mdwn [new file with mode: 0644]
TWiki/TipsContrib.mdwn
TWiki/TwistyContrib.mdwn
TWiki/TwistyPlugin.mdwn
TWiki/UserForm.mdwn [new file with mode: 0644]
TWiki/UsingHTML.mdwn
TWiki/VarACTIVATEDPLUGINS.mdwn
TWiki/VarAQUA.mdwn
TWiki/VarATTACHURL.mdwn
TWiki/VarATTACHURLPATH.mdwn
TWiki/VarAUTHREALM.mdwn
TWiki/VarBASETOPIC.mdwn
TWiki/VarBASEWEB.mdwn
TWiki/VarBB.mdwn
TWiki/VarBB2.mdwn
TWiki/VarBB3.mdwn
TWiki/VarBB4.mdwn
TWiki/VarBLACK.mdwn
TWiki/VarBLUE.mdwn
TWiki/VarBR.mdwn
TWiki/VarBROWN.mdwn
TWiki/VarBULLET.mdwn
TWiki/VarCALC.mdwn [new file with mode: 0644]
TWiki/VarCARET.mdwn [new file with mode: 0644]
TWiki/VarCOMMENT.mdwn [new file with mode: 0644]
TWiki/VarDATE.mdwn
TWiki/VarDISPLAYTIME.mdwn
TWiki/VarDISPLAYTIME2.mdwn
TWiki/VarEDITTABLE.mdwn [new file with mode: 0644]
TWiki/VarENCODE.mdwn
TWiki/VarENDCOLOR.mdwn
TWiki/VarENDSECTION.mdwn
TWiki/VarENV.mdwn [new file with mode: 0644]
TWiki/VarFAILEDPLUGINS.mdwn
TWiki/VarFORMFIELD.mdwn
TWiki/VarGMTIME.mdwn
TWiki/VarGMTIME2.mdwn
TWiki/VarGRAY.mdwn
TWiki/VarGREEN.mdwn
TWiki/VarGROUPS.mdwn
TWiki/VarH.mdwn
TWiki/VarHOMETOPIC.mdwn
TWiki/VarHTTP.mdwn
TWiki/VarHTTPHOST.mdwn
TWiki/VarHTTPS.mdwn
TWiki/VarI.mdwn
TWiki/VarICON.mdwn
TWiki/VarICONURL.mdwn
TWiki/VarICONURLPATH.mdwn
TWiki/VarIF.mdwn
TWiki/VarINCLUDE.mdwn
TWiki/VarINCLUDINGTOPIC.mdwn
TWiki/VarINCLUDINGWEB.mdwn
TWiki/VarLANGUAGE.mdwn
TWiki/VarLIME.mdwn
TWiki/VarLOCALSITEPREFS.mdwn
TWiki/VarLOGIN.mdwn
TWiki/VarLOGOUT.mdwn
TWiki/VarM.mdwn
TWiki/VarMAINWEB.mdwn
TWiki/VarMAKETEXT.mdwn
TWiki/VarMAROON.mdwn
TWiki/VarMETA.mdwn
TWiki/VarMETASEARCH.mdwn
TWiki/VarN.mdwn
TWiki/VarNAVY.mdwn
TWiki/VarNOP.mdwn
TWiki/VarNOTIFYTOPIC.mdwn
TWiki/VarOLIVE.mdwn
TWiki/VarORANGE.mdwn
TWiki/VarP.mdwn
TWiki/VarPINK.mdwn
TWiki/VarPLUGINDESCRIPTIONS.mdwn
TWiki/VarPLUGINVERSION.mdwn
TWiki/VarPUBURL.mdwn
TWiki/VarPUBURLPATH.mdwn
TWiki/VarPURPLE.mdwn
TWiki/VarQ.mdwn
TWiki/VarQUERYPARAMS.mdwn
TWiki/VarQUERYSTRING.mdwn
TWiki/VarRED.mdwn
TWiki/VarREMOTEADDR.mdwn
TWiki/VarREMOTEPORT.mdwn
TWiki/VarREMOTEUSER.mdwn
TWiki/VarRENDERLIST.mdwn [new file with mode: 0644]
TWiki/VarREVINFO.mdwn
TWiki/VarREVINFO2.mdwn
TWiki/VarS.mdwn
TWiki/VarSCRIPTNAME.mdwn
TWiki/VarSCRIPTSUFFIX.mdwn
TWiki/VarSCRIPTURL.mdwn
TWiki/VarSCRIPTURL2.mdwn
TWiki/VarSCRIPTURLPATH.mdwn
TWiki/VarSCRIPTURLPATH2.mdwn
TWiki/VarSEARCH.mdwn
TWiki/VarSERVERTIME.mdwn
TWiki/VarSERVERTIME2.mdwn
TWiki/VarSESSIONID.mdwn
TWiki/VarSESSIONVAR.mdwn
TWiki/VarSESSIONVARIABLE.mdwn
TWiki/VarSILVER.mdwn
TWiki/VarSLIDESHOWEND.mdwn [new file with mode: 0644]
TWiki/VarSLIDESHOWSTART.mdwn [new file with mode: 0644]
TWiki/VarSPACEDTOPIC.mdwn
TWiki/VarSPACEOUT.mdwn
TWiki/VarSTARTINCLUDE.mdwn
TWiki/VarSTARTSECTION.mdwn
TWiki/VarSTATISTICSTOPIC.mdwn
TWiki/VarSTOPINCLUDE.mdwn
TWiki/VarSYSTEMWEB.mdwn [new file with mode: 0644]
TWiki/VarT.mdwn
TWiki/VarTABLE.mdwn [new file with mode: 0644]
TWiki/VarTEAL.mdwn
TWiki/VarTOC.mdwn
TWiki/VarTOC2.mdwn
TWiki/VarTOPIC.mdwn
TWiki/VarTOPICLIST.mdwn
TWiki/VarTWIKIWEB.mdwn
TWiki/VarU.mdwn
TWiki/VarURLPARAM.mdwn
TWiki/VarUSERINFO.mdwn
TWiki/VarUSERNAME.mdwn
TWiki/VarUSERSWEB.mdwn [new file with mode: 0644]
TWiki/VarVAR.mdwn
TWiki/VarVBAR.mdwn
TWiki/VarWEB.mdwn
TWiki/VarWEBLIST.mdwn
TWiki/VarWEBPREFSTOPIC.mdwn
TWiki/VarWHITE.mdwn
TWiki/VarWIKIHOMEURL.mdwn
TWiki/VarWIKINAME.mdwn
TWiki/VarWIKIPREFSTOPIC.mdwn
TWiki/VarWIKITOOLNAME.mdwn
TWiki/VarWIKIUSERNAME.mdwn
TWiki/VarWIKIUSERSTOPIC.mdwn
TWiki/VarWIKIVERSION.mdwn
TWiki/VarX.mdwn
TWiki/VarY.mdwn
TWiki/VarYELLOW.mdwn
TWiki/WebAtomBase.mdwn
TWiki/WebChangesAlert.mdwn
TWiki/WebCreateNewTopic.mdwn [new file with mode: 0644]
TWiki/WebCreateNewTopicTemplate.mdwn [new file with mode: 0644]
TWiki/WebHome.mdwn
TWiki/WebLeftBar.mdwn
TWiki/WebLeftBarExample.mdwn
TWiki/WebLeftBarLogin.mdwn
TWiki/WebLeftBarPersonalTemplate.mdwn
TWiki/WebNotify.mdwn
TWiki/WebPreferences.mdwn
TWiki/WebPreferencesHelp.mdwn
TWiki/WebRssBase.mdwn
TWiki/WebSearch.mdwn
TWiki/WebSearchAdvanced.mdwn
TWiki/WebSiteTools.mdwn
TWiki/WebStatistics.mdwn
TWiki/WebTemplateTopics.mdwn
TWiki/WebTopBar.mdwn
TWiki/WebTopicCreator.mdwn
TWiki/WebTopicNonWikiTemplate.mdwn
TWiki/WebTopicViewTemplate.mdwn
TWiki/WikiName.mdwn
TWiki/WikiReferences.mdwn
TWiki/WikiSyntax.mdwn
TWiki/WikiSyntaxSummary.mdwn
TWiki/WikiWord.mdwn
TWiki/WysiwygPlugin.mdwn
TWiki/WysiwygPluginSettings.mdwn [new file with mode: 0644]
TWiki/YouAreHere.mdwn

diff --git a/Main/ClassicSkinUserViewTemplate.mdwn b/Main/ClassicSkinUserViewTemplate.mdwn
new file mode 100644 (file)
index 0000000..54f98a0
--- /dev/null
@@ -0,0 +1,11 @@
+%TMPL:INCLUDE\{"view"\}%
+
+%TMPL:DEF\{"active\_form"\}%[Edit personal data](http://www.dementia.org/twiki/edit/%WEB%/%TOPIC%?action=form&t=1277827630 Edit personal data)%TMPL:END% %TMPL:DEF\{"inactive\_form"\}% %TMPL:END%
+
+%TMPL:DEF\{"inactive\_edit"\}%<strike>Edit text</strike>%TMPL:END% %TMPL:DEF\{"create\_topic"\}%Cr<span>e</span>ate%TMPL:END% %TMPL:DEF\{"edit\_topic"\}%<span>E</span>dit text%TMPL:END% %TMPL:DEF\{"active\_edit"\}%[****](http://www.dementia.org/twiki/edit/%WEB%/%TOPIC%?action=text&t=1277827630 Edit this topic text)%TMPL:END%
+
+%TMPL:DEF\{"content"\}%
+
+%BR% %TEXT% <a name="TopicEnd"></a>
+
+%TMPL:END%
diff --git a/Main/TWikiAdminUser.mdwn b/Main/TWikiAdminUser.mdwn
new file mode 100644 (file)
index 0000000..d8a27fe
--- /dev/null
@@ -0,0 +1,24 @@
+# <a name="TWiki Administrator User"></a> TWiki Administrator User
+
+The %TOPIC% has been added to TWiki 4.2.0 to make it possible to login without needing to create a TWiki User, or to temporarily login as %TOPIC% using the password set in configure, and then log back out to the same User and Group as before.
+
+This means it is no longer necessary to add yourself to the [[TWikiAdminGroup]], and you will be able to quicky change to Admin User (and back to your user) only when you need to.
+
+### <a name="How to login as %TOPIC%"></a> How to login as %TOPIC%
+
+- Login as the internal TWiki administrator:
+  - %ADMINLOGIN%
+- Logout from Administrator:
+  - click the [[Logout link|Main/LOGOUTURL]]
+
+**_%X% NOTE:_** If you lock yourself out of TWikiAdminUser during setup activities or have forgotten the configure password, you can unset the configure password by editing the `lib/LocalSite.cfg` file and deleting the line that starts with `$TWiki::cfg{Password}` and then set it again by saving your settings in `configure`.
+
+### <a name="Prerequisites"></a> Prerequisites
+
+- `Security Setup : Sessions : {UserClientSession}` needs to be enabled in configure
+- a configure password (otherwise the Admin login is automatically disabled.)
+- If your TWiki is configured to use ApacheLoginManager, you will need to log in as a valid user first.
+
+**_Related topics:_** [[TWikiUsers]], [[TWikiAdminGroup]], [[TWikiGroups]], %SYSTEMWEB%.TWikiAccessControl
+
+----
diff --git a/Main/WebCreateNewTopic.mdwn b/Main/WebCreateNewTopic.mdwn
new file mode 100644 (file)
index 0000000..8b13789
--- /dev/null
@@ -0,0 +1 @@
+
index d8269e8..54ee350 100644 (file)
@@ -28,5 +28,5 @@
 **_Notes:_**
 
 - This topic is updated by the statistics script. (You can also [force](http://www.dementia.org/twiki/statistics/%WEB%) an update)
-- [[TWikiDocumentation]] tells you how to enable the automatic updates of the statistics.
+- %SYSTEMWEB%.TWikiDocumentation tells you how to enable the automatic updates of the statistics.
 - Suggestion: You could archive this topic once a year and delete the previous year's statistics from the table.
index ac9bb7a..97fb91e 100644 (file)
@@ -147,7 +147,7 @@ You may also see in the header (usually at the top right) a list of the TWiki "w
 
 - For example, we might have a web called "Enemies", where we keep all we know about our enemies, and another called "Friends"
 - There's usually a safe play web called something like "Sandbox" or "Scratch", where you can create pages just to try things out
-- And some admin areas, like "Main" and "TWiki"
+- And some admin areas, like "%USERSWEB%" and "%SYSTEMWEB%"
 
 ## <a name="Slide 10: The Page Footer"></a> Slide 10: The Page Footer
 
@@ -187,7 +187,7 @@ The footer of the page is also highlighted in colour, and is usually where you w
 
 ... and easier to read<br /><br />`_Actually_ it is *perfectly* and __absolutely__ flat`<br /><br /> appears as <br /><br />_Actually_ it is **perfectly** and **_absolutely_** flat
 
-- A full description of all the formatting can be found in the [[TextFormattingRules]] and [[TextFormattingFAQ]]
+- A full description of all the formatting can be found in the %SYSTEMWEB%.TextFormattingRules and %SYSTEMWEB%.TextFormattingFAQ
 - The best thing to do is just to type until you get stuck
   - then follow the link on the edit page to the help.
 
@@ -251,7 +251,7 @@ TWiki understands pages in plain text just fine, but you can %RED% **_jazz_** %E
 
          | Cat | Feline |
          | Bear | Ursine |
-         | Wolf | Vulpine |
+         | Wolf | Lupine |
 
 - appears as <table border="1" cellpadding="0" cellspacing="0">
   <tr>
@@ -264,7 +264,7 @@ TWiki understands pages in plain text just fine, but you can %RED% **_jazz_** %E
   </tr>
   <tr>
     <td><font color="black">Wolf</font></td>
-    <td><font color="black">Vulpine</font></td>
+    <td><font color="black">Lupine</font></td>
   </tr>
 </table>
 - %RED% .... %ENDCOLOR% will change the colour of the enclosed text. Lots of colours are available (%RED%%RED%%ENDCOLOR%, %GREEN%%GREEN%%ENDCOLOR%, %BLUE%%BLUE%%ENDCOLOR% etc)
@@ -288,11 +288,11 @@ TWiki understands pages in plain text just fine, but you can %RED% **_jazz_** %E
 - An ordinary URL pasted into text will appear as a link - <http://www.google.com>
   - You can also prettify URLs using square brackets:
     - `[[http://www.google.com/][Google]]` appears as [Google](http://www.google.com/)
-- Use %SEARCH. This is an interface to a sophisticated search engine that embeds the results of the search in your page. See [[TWikiVariables]] for full details.
+- Use %SEARCH. This is an interface to a sophisticated search engine that embeds the results of the search in your page. See %SYSTEMWEB%.TWikiVariables for full details.
 
 ## <a name="Slide 19: More formatting"></a> Slide 19: More formatting
 
-- There's **lots** more formatting available, see [[TextFormattingRules]] and [[TextFormattingFAQ]]
+- There's **lots** more formatting available, see %SYSTEMWEB%.TextFormattingRules and %SYSTEMWEB%.TextFormattingFAQ
 - _If you are a real masochist, you can even enter raw HTML tags!_
 - **Important** to _disable_ unwanted formatting, use `<nop>`
   - `<nop>_word_` appears as \_word\_
index 5e7b1fb..344fd16 100644 (file)
@@ -17,14 +17,16 @@ This depends on the browser you are using (see also cross-browser support below)
   - Press the required letter
   - Release the keys and press the 'ENTER' key
 
-- If you use Netscape Navigator, Mozilla, or Firefox
+- If you use Netscape Navigator, Mozilla, or Firefox 1.0
   - Press and hold the 'Alt' key
   - Press the required letter
 
+- If you use Firefox 2.0
+  - Press and hold both the 'Shift' and the 'Alt' key
+  - Press the required letter
+
 - If you are using a Mac
   - Press and hold the 'Ctrl' key
   - Press the required letter
 
-[Learn more](http://www.salford.gov.uk/online/howto/accesskeys.htm)
-
 **_Related Topics:_** [[UserDocumentationCategory]]
index 51996b6..48e9ce3 100644 (file)
@@ -1,10 +1,12 @@
 # <a name="Administrator Skills Assumptions"></a> Administrator Skills Assumptions
 
-For each of these, the requirement is either pre-existing knowledge/skill, or the willingness to spend significant time (i.e. from hours to days) learning these.
+**_Note:_** If you aren't already fairly well-skilled in Linux/Unix/Windows, Apache, and so on, consider using TWiki:Codev.TWikiVMDebianStable - this can be installed on Windows or Linux, and makes it possible to get a working TWiki system within 5 minutes (after a fairly big download), ready to use from your browser. This is ideal for personal use or evaluations - if you decide to go for production use then these AdminSkillsAssumptions apply to some degree, but you are starting from a working system.
+
+If you need to install TWiki you'll need to either have or learn the following skills (even with TWikiVMDebianStable, you'll need these for upgrades). For each of these, the requirement is either pre-existing knowledge/skill, or the willingness to spend significant time (i.e. from hours to days) learning them:
 
 - **Operating system administration:** Ability to use Unix/Linux command line tools (or equivalent Windows tools), including ability to move/copy/delete files, change permissions, view web server log files, set environment variables, use a text editor, etc.
 - **Web server administration:** Ability to do basic setup, e.g. ability to edit config files or use GUI configuration tools to enable CGI scripts on a directory.
-- **Program compilation:** _Where RCS is not pre-installed_ (that is most Unix systems), the ability to download and compile the RCS program from source, including use of `configure`, `make`, etc. This is often **not** necessary on Linux or Windows.
+- **Program compilation:** _Where Revision Control System (RCS) is not pre-installed_ (that is most Unix systems), the ability to download and compile the RCS program from source, including use of `configure`, `make`, etc. This is often **not** necessary on Linux or Windows.
 - **Troubleshooting**: Ability to perform tests, inspect error logs, talk to technical support (whether in an IT department or web hosting provider) and read documentation in order to help with diagnosing installation problems.
 
 Installing TWiki is **not** recommended for people who only know HTML and web design, unless they are willing to learn the above, or team up with someone who can handle the installation.
@@ -13,8 +15,8 @@ Although the [[TWikiInstallationGuide]] is quite complete, there will on occasio
 
 There are many excellent resources for learning how to administer your OS and web server, including books, web sites, web forums, IM and e-mail lists. The TWiki:Support web must **not** be depended on as a resource for this purpose - in other words, it is not there to answer basic questions about operating system and web server administration. Asking and answering questions is time consuming for all concerned and is best used for specific _TWiki related_ issues, rather than helping you learn the OS and web server.
 
-r.
+To get started with Linux, visit [LinuxBasics.org](http://linuxbasics.org/). LinuxBasics.org offers Linux tutorials, a mailing-list and an IRC-channel to answer questions, and links to sites with information to install and use Linux. LinuxBasics.org now also offers a downloadable Linux 'virtual machine' (LBox) that runs on Windows - you can use this as a completely safe learning environment, and feel free to make mistakes without any chance of damaging your Windows setup.
 
-To get started with Linux, visit <http://linuxbasics.org/>. LinuxBasics.org offers Linux tutorials, a mailing-list and an IRC-channel to answer questions, and links to sites with information to install and use Linux. A nice tool for people migrating from Windows is <http://www.MidnightCommander.org/>. It is already installed on Linux systems: try <code>**mc -ac**</code> and <code>**ESC 1**</code> to get help.
+A nice tool for people migrating from Windows is <http://www.MidnightCommander.org/>. It is already installed on Linux systems: try <code>**mc -ac**</code> and <code>**ESC 1**</code> to get help.
 
 **_Related Topics:_** [[AdminDocumentationCategory]]
index 421a785..7a9e3a3 100644 (file)
@@ -4,7 +4,7 @@ Manage whole **TWiki** site from one screen.
 
 - <img src="http://www.dementia.org/twiki//view/Main/WebHome/help.gif" width="16" height="16" alt="help" /> Documentation: [[TWiki Reference Manual|Main/TWikiReferenceManual]]
 - <img src="http://www.dementia.org/twiki//view/Main/WebHome/wrench.gif" width="16" height="16" alt="wrench" /> [[Site Tools|Main/TWikiSiteTools]]: [Configure](http://www.dementia.org/twiki/configure), [[TWikiPreferences]], [[InterWikis]], [[Variables|Main/TWikiVariables]], [[Doc Graphics|Main/TWikiDocGraphics]]
-- <img src="http://www.dementia.org/twiki//view/Main/WebHome/persons.gif" width="16" height="16" alt="persons" /> Manage [[Users|Main/TWikiUsers]]: [[Register|Main/TWikiRegistration]], [[NewUserTemplate]], [[UserForm]], [[ResetPassword]], [[ChangePassword]]
+- <img src="http://www.dementia.org/twiki//view/Main/WebHome/persons.gif" width="16" height="16" alt="persons" /> Manage [[Users|USERSWEB/TWikiUsers]]: [[Register|Main/TWikiRegistration]], %SYSTEMWEB%.NewUserTemplate, %SYSTEMWEB%.UserForm, [[ResetPassword]], [[ChangePassword]]
 - <img src="http://www.dementia.org/twiki//view/Main/WebHome/indexlist.gif" width="16" height="16" alt="indexlist" /> Manage Content: [[Topics|Main/ManagingTopics]], [[Webs|Main/ManagingWebs]], [[YouAreHere]]
 - <img src="http://www.dementia.org/twiki//view/Main/WebHome/folder.gif" width="16" height="16" alt="folder" /> Webs: <table bgcolor="#000000" border="0" cellpadding="3" cellspacing="2" width="100%">
   <tr bgcolor="#99CCCC">
@@ -24,18 +24,18 @@ Manage whole **TWiki** site from one screen.
   <tr bgcolor="#ffffff">
     <td valign="top"> Legend: </td>
     <td valign="top">  </td>
-    <td valign="top"><img alt="Home of web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/home.gif" width="16" /> WebHome </td>
-    <td valign="top"><img alt="Search web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/searchtopic.gif" width="16" /> WebSearch </td>
-    <td valign="top"><img alt="Recent changes in the web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/recentchanges.gif" width="16" /> WebChanges </td>
-    <td valign="top"><img alt="Get notified of changes to the web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/notify.gif" width="16" /> WebNotify </td>
+    <td valign="top"><img alt="Home of web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/home.gif" width="16" /> WebHome </td>
+    <td valign="top"><img alt="Search web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/searchtopic.gif" width="16" /> WebSearch </td>
+    <td valign="top"><img alt="Recent changes in the web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/recentchanges.gif" width="16" /> WebChanges </td>
+    <td valign="top"><img alt="Get notified of changes to the web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/notify.gif" width="16" /> WebNotify </td>
   </tr>
   <tr bgcolor="#ffffff">
     <td valign="top">  </td>
     <td valign="top">  </td>
-    <td valign="top"><img alt="Preferences of web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/wrench.gif" width="16" /> WebPreferences </td>
-    <td valign="top"><img alt="Statistics of web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/statistics.gif" width="16" /> WebStatistics </td>
-    <td valign="top"><img alt="Bullet list of all topics" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/indexlist.gif" width="16" /> WebTopicList </td>
-    <td valign="top"><img alt="Index of all topics" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/index.gif" width="16" /> WebIndex </td>
+    <td valign="top"><img alt="Preferences of web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/wrench.gif" width="16" /> WebPreferences </td>
+    <td valign="top"><img alt="Statistics of web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/statistics.gif" width="16" /> WebStatistics </td>
+    <td valign="top"><img alt="Bullet list of all topics" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/indexlist.gif" width="16" /> WebTopicList </td>
+    <td valign="top"><img alt="Index of all topics" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/index.gif" width="16" /> WebIndex </td>
   </tr>
 </table>
 
index 9b425f5..b29b40e 100644 (file)
@@ -1,3 +1,11 @@
+<a name="EncodeURLsUTF8"></a>
+
+# <a name="Appendix B: Encode URLs With UTF"></a> Appendix B: Encode URLs With UTF8
+
+_Use internationalised characters within WikiWords and attachment names_
+
+This topic addresses implemented UTF-8 support for URLs only. The overall plan for UTF-8 support for TWiki is described in TWiki:Codev.ProposedUTF8SupportForI18N.
+
 <div>
   <ul>
     <li><a href="#Appendix B: Encode URLs With UTF"> Appendix B: Encode URLs With UTF8 </a><ul>
@@ -9,14 +17,6 @@
   </ul>
 </div>
 
-<a name="EncodeURLsUTF8"></a>
-
-# <a name="Appendix B: Encode URLs With UTF"></a> Appendix B: Encode URLs With UTF8
-
-_Use internationalised characters within WikiWords and attachment names_
-
-This topic addresses implemented UTF-8 support for URLs only. The overall plan for UTF-8 support for TWiki is described in TWiki:Codev.ProposedUTF8SupportForI18N.
-
 ## <a name="Current Status"></a> Current Status
 
 To simplify use of internationalised characters within [[WikiWords]] and attachment names, TWiki now supports UTF-8 URLs, converting on-the-fly to virtually any character set, including ISO-8859-\*, KOI8-R, EUC-JP, and so on.
index 1c674ba..60360fa 100644 (file)
@@ -2,17 +2,20 @@
 
 This contrib packages the third-party `Behaviour` Javascript event library, available from <http://bennolan.com/behaviour/>.
 
-Behaviour is suited to create javascript based interaction that degrades well when javascript is not available.
-
-Javascript file: [behaviour.js](http://www.dementia.org/twiki//view/TWiki/%TOPIC%/behaviour.js) (8.1K). The [compressed javascript file](http://www.dementia.org/twiki//view/TWiki/%TOPIC%/behaviour.compressed.js) (2.9K) has been processed by [ShrinkSafe](http://alex.dojotoolkit.org/shrinksafe/).
+Behaviour uses CSS selectors to subscribe to javascript event handlers. This allows to create clean code, separated from HTML (and well suited to create javascript based interaction that degrades nicely when javascript is not available).
 
 <div><span>On this page:</span><ul>
     <li><a href="#Introduction"> Introduction</a></li>
-    <li><a href="#Usage"> Usage</a></li>
-    <li><a href="#Example"> Example</a></li>
+    <li><a href="#Usage"> Usage</a><ul>
+        <li><a href="#Example"> Example</a></li>
+        <li><a href="#Leaking danger"> Leaking danger</a></li>
+      </ul>
+    </li>
     <li><a href="#Development"> Development</a></li>
     <li><a href="#License"> License</a></li>
     <li><a href="#Links"> Links</a></li>
+    <li><a href="#Installation Instructions"> Installation Instructions</a></li>
+    <li><a href="#Contrib Settings"> Contrib Settings</a></li>
     <li><a href="#Contrib Info"> Contrib Info</a></li>
   </ul>
 </div>
@@ -62,7 +65,7 @@ From the website:
 
 Include the javascript file:
 
-> <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/BehaviourContrib/behaviour.compressed.js"></script>
+> <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/BehaviourContrib/behaviour.js"></script>
 
 In your code you create a "rules" object, with sub-objects for each html element class name or id:
 
@@ -96,83 +99,191 @@ Apply the rules with:
 
 > Behaviour.register(myrules);
 
-## <a name="Example"></a> Example
+### <a name="Example"></a> Example
 
 If we have a 'normal' link to TWiki Web hometopic: [[TWiki Web Home|TWiki/WebHome]], we can use javascript to make it open a popup window. When javascript is not available the link behaviour defaults to opening the page in the current window.
 
-> <span class="link%TWIKIWEB%%HOMETOPIC%">[[%TWIKIWEB%.%HOMETOPIC%][TWiki Web Home]]</span>
+> <div id="demoblock" style="padding:1em; width:100px; text-align:center;">
+>     MOUSE OVER ME
+>     </div>
 >
 >     <script type="text/javascript">
 >     // <![CDATA[
 >     var myrules = {
->        '.link%TWIKIWEB%%HOMETOPIC% a' : function(el){
->           el.onclick = function() {
->              // open in a popup with no other attributes than template 'viewplain'
->              launchTheWindow(this.href,null,null,null,"viewplain");
+>        '#demoblock' : function(el) {
+>           var defaultColor = '#A3D6F8';
+>           var highlightColor = '#4A7FB5';
+>
+>           el.style.backgroundColor = defaultColor;
+>
+>           el.onmouseover = function() {
+>              this.style.backgroundColor = highlightColor;
+>              return false;
+>           }
+>           el.onmouseout = function() {
+>              this.style.backgroundColor = defaultColor;
+>              return false;
+>           }
+>        },
+>        '#demoblock span' : function(el) {
+>
+>           var text = el.innerHTML;
+>
+>           var fisherYates = function (inArray) {
+>             var i = inArray.length;
+>             if ( i == 0 ) return false;
+>             while ( --i ) {
+>               var j = Math.floor( Math.random() * ( i + 1 ) );
+>               var tempi = inArray[i];
+>               var tempj = inArray[j];
+>               inArray[i] = tempj;
+>               inArray[j] = tempi;
+>              }
+>           }
+>
+>           var randomize = function(inText) {
+>              var letters = inText.split('');
+>              fisherYates(letters);
+>              return letters.join('');
+>           }
+>           el.onmouseover = function() {
+>              this.innerHTML = randomize(text);
+>              return false;
+>           }
+>           el.onmouseout = function() {
+>              this.innerHTML = text;
 >              return false;
 >           }
 >        }
 >     };
->
 >     Behaviour.register(myrules);
 >     // ]]>
 >     </script>
 >
-> The class name `link%TWIKIWEB%%HOMETOPIC%` will get expanded to `linkTWikiWebHome`
-
-Creates:
-
-<span>[[TWiki Web Home|TWiki/WebHome]]</span>
-
-## <a name="Development"></a> Development
-
-- [Google Groups: Behaviour Javascript Library](http://groups.google.com/group/behaviour)
-- [Dean Edwards: Faster DOM Queries](http://dean.edwards.name/weblog/2006/03/faster/) - with a speed-up hack to Behaviour
-
-## <a name="License"></a> License
-
-Behaviour is freely distributable under the terms of an BSD license. For details, see the Behaviour website.
-
-## <a name="Links"></a> Links
-
-- [Behaviour website](http://bennolan.com/behaviour/)
-- [Behaviour Google Group](http://groups.google.com/group/behaviour)
-
-## <a name="Contrib Info"></a> Contrib Info
-
-<table border="1" cellpadding="0" cellspacing="0">
-  <tr>
-    <td> Author: </td>
-    <td> TWiki:Main.ArthurClemens </td>
-  </tr>
-  <tr>
-    <td> Copyright: </td>
-    <td> version 1.1 - Copyright (c) Ben Nolan and Simon Willison </td>
-  </tr>
-  <tr>
-    <td> License: </td>
-    <td> BSD </td>
-  </tr>
-  <tr>
-    <td> Dependencies: </td>
-    <td> None </td>
-  </tr>
-  <tr>
-    <td> 4 June 2006 </td>
-    <td> 1.000 First Version. Included Behaviour version: 1.1 </td>
-  </tr>
-  <tr>
-    <td align="right"> Home: </td>
-    <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
-  </tr>
-  <tr>
-    <td align="right"> Feedback: </td>
-    <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
-  </tr>
-  <tr>
-    <td align="right"> Appraisal: </td>
-    <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
-  </tr>
-</table>
-
-**_Related Topics:_** [[TWikiPreferences]]
+> Creates:
+>
+> <div id="demoblock" style="padding: 1em; width: 150px; text-align: center"><span>MOUSE OVER ME</span></div>
+>
+> ### <a name="Leaking danger"></a> Leaking danger
+>
+> Behaviour code leaks memory on Windows Explorer prior to version 7. To prevent leaking, set the element variable to
+>
+> `null`
+>
+> :
+>
+> > var myrules = {
+> >        'table.test td' : function(element) {
+> >           element.onmouseover = function() {
+> >              this.style.backgroundColor = highlightColor;
+> >              return false;
+> >           }
+> >           element = null; // by setting this IE will not leak
+> >        }
+> >     };
+> >     Behaviour.register(myrules);
+>
+> ## <a name="Development"></a> Development
+>
+> - [Google Groups: Behaviour Javascript Library](http://groups.google.com/group/behaviour)
+> - [Nabble - Behaviour Javascript Library forum &amp; mailing list archive](http://www.nabble.com/Behaviour-Javascript-Library-f16264.html)
+> - [Behaviour2](http://groups.google.com/group/behaviour/browse_thread/thread/e9828f9fdb482ac1/8ca704730053e23f?#8ca704730053e23f) - update in the making, since 2006
+>
+> ## <a name="License"></a> License
+>
+> Behaviour is freely distributable under the terms of an BSD license. For details see the Behaviour website.
+>
+> ## <a name="Links"></a> Links
+>
+> - [Behaviour website](http://bennolan.com/behaviour/)
+> - [Behaviour Google Group](http://groups.google.com/group/behaviour)
+>
+> ## <a name="Installation Instructions"></a> Installation Instructions
+>
+> You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
+>
+> Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
+>
+> - If you have TWiki 4.2 or later, you can install from the `configure` interface (Go to Plugins-&gt;Find More Extensions)
+>   - See the [installation supplement](http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement) on TWiki.org for more information.
+> - If you have any problems, then you can still install manually from the command-line:
+>   1. Download one of the `.zip` or `.tgz` archives
+>   2. Unpack the archive in the root directory of your TWiki installation.
+>   3. Run the installer script ( `perl <module>_installer` )
+>   4. Run `configure` and enable the module, if it is a plugin.
+>   5. Repeat for any missing dependencies.
+> - If you are **still** having problems, then instead of running the installer script:
+>   1. Make sure that the file permissions allow the webserver user to access all files.
+>   2. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
+>   3. Manually edit LocalSite.cfg to set any configuration variables.
+>
+> <div class="twikiAlert">%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your [[Main/TWikiPreferences]], if they are not already there:<br /><pre>   * Set SYSTEMWEB = %TWIKIWEB%<br />   * Set USERSWEB = %MAINWEB%</pre></div>
+>
+> ## <a name="Contrib Settings"></a> Contrib Settings
+>
+> - Set SHORTDESCRIPTION = `Behaviour` Javascript event library to create javascript based interactions that degrade well when javascript is not available
+>
+> You can also set the global TWiki variable BEHAVIOURCONTRIB\_DEBUG to 1 to make the contrib use uncompressed javascript sources, in the event of problems.
+>
+> ## <a name="Contrib Info"></a> Contrib Info
+>
+> <table border="1" cellpadding="0" cellspacing="0">
+>   <tr>
+>     <td align="right"> Author: </td>
+>     <td> TWiki:Main.ArthurClemens </td>
+>   </tr>
+>   <tr>
+>     <td align="right"> Copyright: </td>
+>     <td> Code: <code>behaviour.js</code> version 1.1 - Copyright (c) Ben Nolan and Simon Willison. TWiki distribution and updates/additions: TWiki:Main.ArthurClemens. </td>
+>   </tr>
+>   <tr>
+>     <td align="right"> License: </td>
+>     <td> BSD </td>
+>   </tr>
+>   <tr>
+>     <td align="right"> Version: </td>
+>     <td> 15675 (22 Jan 2008) </td>
+>   </tr>
+>   <tr>
+>     <td align="right"> Dependencies: </td>
+>     <td> None </td>
+>   </tr>
+>   <tr>
+>     <td align="right"> Contrib Version: </td>
+>     <td> 1.3.1 </td>
+>   </tr>
+>   <tr>
+>     <td align="right"> Change History: </td>
+>     <td>  </td>
+>   </tr>
+>   <tr>
+>     <td align="right"> 17 Oct 2007 </td>
+>     <td> 1.3 Replaced "faster code" by other code from Dean Edwards, [[ packed by <a href="http://groups.google.com/group/behaviour/browse_thread/thread/85137977bedf5ed/3cf3ba8065d41a8c#3cf3ba8065d41a8c][Raymond" target="_top">http://groups.google.com/group/behaviour/browse_thread/thread/85137977bedf5ed/3cf3ba8065d41a8c#3cf3ba8065d41a8c][Raymond</a> Irving]]. </td>
+>   </tr>
+>   <tr>
+>     <td align="right"> 02 Jul 2007 </td>
+>     <td> 1.2 Integrated other faster code by Dean Edwards: <a href="http://dean.edwards.name/weblog/2006/06/again/" target="_top">faster onload (again)</a>. </td>
+>   </tr>
+>   <tr>
+>     <td align="right"> 08 Mar 2007 </td>
+>     <td> 1.1 Integrated code by Dean Edwards (see [[Main/WebHome#CodeUpdate]]). </td>
+>   </tr>
+>   <tr>
+>     <td align="right"> 04 Jun 2006 </td>
+>     <td> 1.0 First Version. Included Behaviour version: 1.1. </td>
+>   </tr>
+>   <tr>
+>     <td align="right"> Home: </td>
+>     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
+>   </tr>
+>   <tr>
+>     <td align="right"> Feedback: </td>
+>     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
+>   </tr>
+>   <tr>
+>     <td align="right"> Appraisal: </td>
+>     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
+>   </tr>
+> </table>
+>
+> **_Related Topics:_** [[TWikiPreferences]]
index 2909d98..a99212f 100644 (file)
@@ -1,6 +1,6 @@
 # <a name="Bulk Registration"></a> Bulk Registration
 
-The [[TWikiAdminGroup]] can use %TOPIC% to register (i.e. create logins and [[UserTopics]]) for a group of people quickly. Create a table in the REGISTERTOPIC named below, setting each row to represent each user and each column to correspond to the metadata. Then press the button on this page to perform registration for those users. Unlike normal registration the administrator is assumed to have correct e-mail addresses for the users, so no verification is required. Note that the new users are not notified that they have an account. This is so you can prepare and verify the accounts before announcing them. To announce them use the [[BulkResetPassword]] feature: this will assign a new random password and notify users.
+Administrators can use this topic to register (i.e. create logins and [[UserTopics]]) for a group of people quickly. Create a table in the REGISTERTOPIC named below, setting each row to represent each user and each column to correspond to the metadata. Then press the button on this page to perform registration for those users. Unlike normal registration the administrator is assumed to have correct e-mail addresses for the users, so no verification is required. Note that the new users are not notified that they have an account. This is so you can prepare and verify the accounts before announcing them. To announce them use the [[BulkResetPassword]] feature: this will assign a new random password and notify users.
 
 ## <a name="Bulk Registration usage"></a> Bulk Registration usage
 
@@ -10,8 +10,7 @@ If you use the [[UserForm]] then ensure that it contains all the fields you defi
 
 ### <a name="Mandatory fields"></a> Mandatory fields
 
-- [[WikiName]]
-- Email
+- WikiName
 - FirstName
 - LastName
 
@@ -21,10 +20,12 @@ If you use the [[UserForm]] then ensure that it contains all the fields you defi
 
 ## <a name="Settings"></a> Settings
 
-- - Set REGISTERTOPIC = [[UnprocessedRegistrations]]
+- Define where to pick up the table of users to register
+  - Set REGISTERTOPIC = [[UnprocessedRegistrations]]
+- Use this to define where to log the bulk registration process. It needs to be a topic name in this web.
   - Set LOGTOPIC = %REGISTERTOPIC%Log
-
-- - Set OVERWRITEHOMETOPICS = 0
+- Set this to 1 to make the bulk registration overwrite any existing user topics. By default, existing user topics are left alone.
+  - Set OVERWRITEHOMETOPICS = 0
 
 ### <a name="Example format"></a> Example format
 
@@ -45,10 +46,12 @@ To use this:
 Notes:
 
 1. The first row of the table dictates the heading format and that the fieldnames must be plain, i.e. **must not contain bolded** entries.
-2. You are responsible for ensuring that the fieldnames appear in the [[Main.UserForm|Main/UserForm]]
-3. Only members of the [[TWikiAdminGroup]] can run this.
+2. You are responsible for ensuring that the fieldnames appear in the [[TWiki.UserForm|TWiki/UserForm]]
+3. Only administrators can run this.
+
+**Sorry, the password system is currently read only, please contact 0**<br />
 
-<form action="http://www.dementia.org/twiki/manage/%REGISTERTOPIC%" method="post" name="bulkRegister"><input name="action" type="hidden" value="bulkRegister" /> <input type="submit" value="Bulk Register these people" /> <input name="LogTopic" type="hidden" value="%LOGTOPIC%" /> <input name="OverwriteHomeTopics" type="hidden" value="%OVERWRITEHOMETOPICS%" /></form>
+<form action="http://www.dementia.org/twiki/manage/%REGISTERTOPIC%" method="post" name="bulkRegister"><input name="action" type="hidden" value="bulkRegister" />  <input %notmodifyable%="%NOTMODIFYABLE%" type="submit" value="Bulk Register these people" /> <input name="LogTopic" type="hidden" value="%LOGTOPIC%" /> <input name="OverwriteHomeTopics" type="hidden" value="%OVERWRITEHOMETOPICS%" /></form>
 
 ## <a name="%REGISTERTOPIC%"></a> %REGISTERTOPIC%
 
index c832631..221a6a2 100644 (file)
@@ -1,20 +1,15 @@
 # <a name="Bulk Reset Passwords"></a> Bulk Reset Passwords
 
-**The [[TWikiAdminGroup]] can use this topic to reset any number of user passwords.**
+**Administrators can use this topic to reset any number of user passwords.**
 
 Users whose passwords are reset with this will be sent an e-mail at the address recorded **in their home topic**. The administrator will **not** be told the new passwords.
 
 **Follow these two steps:**
 
-<form action="http://www.dementia.org/twiki/resetpasswd/%WEB%/%TOPIC%" method="post">
+<form action="http://www.dementia.org/twiki/manage/%WEB%/%TOPIC%" method="post">
   <div>
     <div>
-      <h3><a name="Select users"></a> Select users </h3>
-      <p>
-      </p>
-      <p>
-      </p>
-      <h1><a name="TWiki Installation Error"></a> TWiki Installation Error </h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags) <p><strong><em>Note</em></strong> if you don't see all the users you expect in this table, make sure their home topic has an attached [[Main/UserForm]]. This is used to identify users. </p>
+      <h3><a name="Select users"></a> Select users </h3><strong>Sorry, the password system is currently read only, please contact 0</strong><h1><a name="TWiki Installation Error"></a> TWiki Installation Error </h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags) <p><strong><em>Note</em></strong> if you don't see all the users you expect in this table, make sure their home topic has an attached [[TWiki/UserForm]]. This is used to identify users. </p>
     </div>
     <div>
       <h3><a name="Write message"></a> Write message </h3>
@@ -23,7 +18,7 @@ Users whose passwords are reset with this will be sent an e-mail at the address
 Welcome! The site is ready for your use. Please use the login name and password listed below and contact me if you have any questions.
 </textarea>
     </div>
-    <div><input name="action" type="hidden" value="resetPassword" /> <input type="submit" value="Reset selected user passwords and send message" /></div>
+    <div><input name="action" type="hidden" value="resetPassword" /> <input %notmodifyable%="%NOTMODIFYABLE%" type="submit" value="Reset selected user passwords and send message" /></div>
   </div>
 </form>
 
diff --git a/TWiki/CGISessionDotPm.mdwn b/TWiki/CGISessionDotPm.mdwn
new file mode 100644 (file)
index 0000000..af597c1
--- /dev/null
@@ -0,0 +1,571 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+**extends** `CGI::Session::ErrorHandler `
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session - persistent session data in CGI applications
+
+=head1 SYNOPSIS
+
+# Object initialization: use CGI::Session; $session = new CGI::Session();
+
+$CGISESSID = $session-&gt;id();
+
+# send proper HTTP header with cookies: print $session-&gt;header();
+
+# storing data in the session $session-&gt;param('f\_name', 'Sherzod'); # or $session-&gt;param(-name=&gt;'l\_name', -value=&gt;'Ruzmetov');
+
+# flush the data from memory to the storage driver at least before your # program finishes since auto-flushing can be unreliable $session-&gt;flush();
+
+# retrieving data my $f\_name = $session-&gt;param('f\_name'); # or my $l\_name = $session-&gt;param(-name=&gt;'l\_name');
+
+# clearing a certain session parameter $session-&gt;clear(["l\_name", "f\_name"]);
+
+# expire '\_is\_logged\_in' flag after 10 idle minutes: $session-&gt;expire('is\_logged\_in', '+10m')
+
+# expire the session itself after 1 idle hour $session-&gt;expire('+1h');
+
+# delete the session for good $session-&gt;delete();
+
+=head1 DESCRIPTION
+
+CGI-Session is a Perl5 library that provides an easy, reliable and modular session management system across HTTP requests. Persistency is a key feature for such applications as shopping carts, login/authentication routines, and application that need to carry data across HTTP requests. CGI::Session does that and many more.
+
+=head1 TRANSLATIONS
+
+This document is also available in Japanese.
+
+=over 4
+
+=item o
+
+Translation based on 4.14: <http://digit.que.ne.jp/work/index.cgi?Perldoc/ja>
+
+=item o
+
+Translation based on 3.11, including Cookbook and Tutorial: <http://perldoc.jp/docs/modules/CGI-Session-3.11/>
+
+=back
+
+=head1 TO LEARN MORE
+
+Current manual is optimized to be used as a quick reference. To learn more both about the philosophy and CGI::Session programming style, consider the following:
+
+=over 4
+
+=item \*
+
+L&lt;CGI::Session::Tutorial|CGI::Session::Tutorial&gt; - extended CGI::Session manual. Also includes library architecture and driver specifications.
+
+=item \*
+
+We also provide mailing lists for CGI::Session users. To subscribe to the list or browse the archives visit <https://lists.sourceforge.net/lists/listinfo/cgi-session-user>
+
+=item \*
+
+B - "HTTP State Management Mechanism" found at <ftp://ftp.isi.edu/in-notes/rfc2965.txt>
+
+=item \*
+
+L&lt;CGI|CGI&gt; - standard CGI library
+
+=item \*
+
+L&lt;Apache::Session|Apache::Session&gt; - another fine alternative to CGI::Session.
+
+=back
+
+=head1 METHODS
+
+Following is the overview of all the available methods accessible via CGI::Session object.
+
+=head2 new()
+
+=head2 new( $sid )
+
+=head2 new( $query )
+
+=head2 new( $dsn, $query||$sid )
+
+=head2 new( $dsn, $query||$sid, \\%dsn\_args )
+
+Constructor. Returns new session object, or undef on failure. Error message is accessible through L&lt;errstr() - class method|CGI::Session::ErrorHandler/errstr&gt;. If called on an already initialized session will re-initialize the session based on already configured object. This is only useful after a call to L&lt;load()|/"load"&gt;.
+
+Can accept up to three arguments, $dsn - Data Source Name, $query||$sid - query object OR a string representing session id, and finally, \\%dsn\_args, arguments used by $dsn components.
+
+If called without any arguments, $dsn defaults to I&lt;driver:file;serializer:default;id:md5&gt;, $query||$sid defaults to C&lt;&lt; CGI-&gt;new() &gt;&gt;, and C&lt;\\%dsn\_args&gt; defaults to I.
+
+If called with a single argument, it will be treated either as C&lt;$query&gt; object, or C&lt;$sid&gt;, depending on its type. If argument is a string , C&lt;new()&gt; will treat it as session id and will attempt to retrieve the session from data store. If it fails, will create a new session id, which will be accessible through L&lt;id() method|/"id"&gt;. If argument is an object, L&lt;cookie()|CGI/cookie&gt; and L&lt;param()|CGI/param&gt; methods will be called on that object to recover a potential C&lt;$sid&gt; and retrieve it from data store. If it fails, C&lt;new()&gt; will create a new session id, which will be accessible through L&lt;id() method|/"id"&gt;. C&lt;name()&gt; will define the name of the query parameter and/or cookie name to be requested, defaults to I.
+
+If called with two arguments first will be treated as $dsn, and second will be treated as $query or $sid or undef, depending on its type. Some examples of this syntax are:
+
+$s = CGI::Session-&gt;new("driver:mysql", undef); $s = CGI::Session-&gt;new("driver:sqlite", $sid); $s = CGI::Session-&gt;new("driver:db\_file", $query); $s = CGI::Session-&gt;new("serializer:storable;id:incr", $sid); # etc...
+
+Following data source components are supported:
+
+=over 4
+
+=item \*
+
+B - CGI::Session driver. Available drivers are L&lt;file|CGI::Session::Driver::file&gt;, L&lt;db\_file|CGI::Session::Driver::db\_file&gt;, L&lt;mysql|CGI::Session::Driver::mysql&gt; and L&lt;sqlite|CGI::Session::Driver::sqlite&gt;. Third party drivers are welcome. For driver specs consider L&lt;CGI::Session::Driver|CGI::Session::Driver&gt;
+
+=item \*
+
+B - serializer to be used to encode the data structure before saving in the disk. Available serializers are L&lt;storable|CGI::Session::Serialize::storable&gt;, L&lt;freezethaw|CGI::Session::Serialize::freezethaw&gt; and L&lt;default|CGI::Session::Serialize::default&gt;. Default serializer will use L&lt;Data::Dumper|Data::Dumper&gt;.
+
+=item \*
+
+B - ID generator to use when new session is to be created. Available ID generator is L&lt;md5|CGI::Session::ID::md5&gt;
+
+=back
+
+For example, to get CGI::Session store its data using DB\_File and serialize data using [[FreezeThaw]]:
+
+$s = new CGI::Session("driver:DB\_File;serializer:FreezeThaw", undef);
+
+If called with three arguments, first two will be treated as in the previous example, and third argument will be C&lt;\\%dsn\_args&gt;, which will be passed to C&lt;$dsn&gt; components (namely, driver, serializer and id generators) for initialization purposes. Since all the $dsn components must initialize to some default value, this third argument should not be required for most drivers to operate properly.
+
+undef is acceptable as a valid placeholder to any of the above arguments, which will force default behavior.
+
+=head2 load()
+
+=head2 load($query||$sid)
+
+=head2 load($dsn, $query||$sid)
+
+=head2 load($dsn, $query, \\%dsn\_args);
+
+Accepts the same arguments as new(), and also returns a new session object, or undef on failure. The difference is, L&lt;new()|/"new"&gt; can create new session if it detects expired and non-existing sessions, but C&lt;load()&gt; does not.
+
+C&lt;load()&gt; is useful to detect expired or non-existing sessions without forcing the library to create new sessions. So now you can do something like this:
+
+$s = CGI::Session-&gt;load() or die CGI::Session-&gt;errstr(); if ( $s-&gt;is\_expired ) \{ print $s-&gt;header(), $cgi-&gt;start\_html(), $cgi-&gt;p("Your session timed out! Refresh the screen to start new session!") $cgi-&gt;end\_html(); exit(0); \}
+
+if ( $s-&gt;is\_empty ) \{ $s = $s-&gt;new() or die $s-&gt;errstr; \}
+
+Notice, all I sessions are empty, but not all I sessions are expired!
+
+=head2 id()
+
+Returns effective ID for a session. Since effective ID and claimed ID can differ, valid session id should always be retrieved using this method.
+
+=head2 param($name)
+
+=head2 param(-name=E$name)
+
+Used in either of the above syntax returns a session parameter set to $name or undef if it doesn't exist. If it's called on a deleted method param() will issue a warning but return value is not defined.
+
+=head2 param($name, $value)
+
+=head2 param(-name=E$name, -value=E$value)
+
+Used in either of the above syntax assigns a new value to $name parameter, which can later be retrieved with previously introduced param() syntax. C&lt;$value&gt; may be a scalar, arrayref or hashref.
+
+Attempts to set parameter names that start with I will trigger a warning and undef will be returned.
+
+=head2 param\_hashref()
+
+B. Use L&lt;dataref()|/"dataref"&gt; instead.
+
+=head2 dataref()
+
+Returns reference to session's data table:
+
+$params = $s-&gt;dataref(); $sid = $params-&gt;\{\_SESSION\_ID\}; $name= $params-&gt;\{name\}; # etc...
+
+Useful for having all session data in a hashref, but too risky to update.
+
+=head2 save\_param()
+
+=head2 save\_param($query)
+
+=head2 save\_param($query, \\@list)
+
+Saves query parameters to session object. In other words, it's the same as calling L&lt;param($name, $value)|/"param"&gt; for every single query parameter returned by C&lt;&lt; $query-&gt;param() &gt;&gt;. The first argument, if present, should be either CGI object or any object which can provide param() method. If it's undef, defaults to the return value of L&lt;query()|/"query"&gt;, which returns C&lt;&lt; CGI-&gt;new &gt;&gt;. If second argument is present and is a reference to an array, only those query parameters found in the array will be stored in the session. undef is a valid placeholder for any argument to force default behavior.
+
+=head2 load\_param()
+
+=head2 load\_param($query)
+
+=head2 load\_param($query, \\@list)
+
+Loads session parameters into a query object. The first argument, if present, should be query object, or any other object which can provide param() method. If second argument is present and is a reference to an array, only parameters found in that array will be loaded to the query object.
+
+=head2 clear()
+
+=head2 clear('field')
+
+=head2 clear(\\@list)
+
+Clears parameters from the session object.
+
+With no parameters, all fields are cleared. If passed a single parameter or a reference to an array, only the named parameters are cleared.
+
+=head2 flush()
+
+Synchronizes data in memory with the copy serialized by the driver. Call flush() if you need to access the session from outside the current session object. You should at least call flush() before your program exits.
+
+As a last resort, CGI::Session will automatically call flush for you just before the program terminates or session object goes out of scope. This automatic behavior was the recommended behavior until the 4.x series. Automatic flushing has since proven to be unreliable, and in some cases is now required in places that worked with 3.x. For further details see:
+
+<http://rt.cpan.org/Ticket/Display.html?id=17541> <http://rt.cpan.org/Ticket/Display.html?id=17299>
+
+=head2 atime()
+
+Read-only method. Returns the last access time of the session in seconds from epoch. This time is used internally while auto-expiring sessions and/or session parameters.
+
+=head2 ctime()
+
+Read-only method. Returns the time when the session was first created in seconds from epoch.
+
+=head2 expire()
+
+=head2 expire($time)
+
+=head2 expire($param, $time)
+
+Sets expiration interval relative to L&lt;atime()|/"atime"&gt;.
+
+If used with no arguments, returns the expiration interval if it was ever set. If no expiration was ever set, returns undef. For backwards compatibility, a method named C&lt;etime()&gt; does the same thing.
+
+Second form sets an expiration time. This value is checked when previously stored session is asked to be retrieved, and if its expiration interval has passed, it will be expunged from the disk immediately. Passing 0 cancels expiration.
+
+By using the third syntax you can set the expiration interval for a particular session parameter, say I&lt;~logged-in&gt;. This would cause the library call clear() on the parameter when its time is up. Note it only makes sense to set this value to something I than when the whole session expires. Passing 0 cancels expiration.
+
+All the time values should be given in the form of seconds. Following keywords are also supported for your convenience:
+
++-----------+---------------+
+
+<table border="1" cellpadding="0" cellspacing="0">
+  <tr>
+    <td align="center"> alias </td>
+    <td align="center"> meaning </td>
+  </tr>
+</table>
+
++-----------+---------------+
+
+<table border="1" cellpadding="0" cellspacing="0">
+  <tr>
+    <td align="center"> s </td>
+    <td align="center"> Second </td>
+  </tr>
+  <tr>
+    <td align="center"> m </td>
+    <td align="center"> Minute </td>
+  </tr>
+  <tr>
+    <td align="center"> h </td>
+    <td align="center"> Hour </td>
+  </tr>
+  <tr>
+    <td align="center"> d </td>
+    <td align="center"> Day </td>
+  </tr>
+  <tr>
+    <td align="center"> w </td>
+    <td align="center"> Week </td>
+  </tr>
+  <tr>
+    <td align="center"> M </td>
+    <td align="center"> Month </td>
+  </tr>
+  <tr>
+    <td align="center"> y </td>
+    <td align="center"> Year </td>
+  </tr>
+</table>
+
++-----------+---------------+
+
+Examples:
+
+$session-&gt;expire("2h"); # expires in two hours $session-&gt;expire(0); # cancel expiration $session-&gt;expire("~logged-in", "10m"); # expires '~logged-in' parameter after 10 idle minutes
+
+Note: all the expiration times are relative to session's last access time, not to its creation time. To expire a session immediately, call L&lt;delete()|/"delete"&gt;. To expire a specific session parameter immediately, call L&lt;clear([$name])|/"clear"&gt;.
+
+=head2 is\_new()
+
+Returns true only for a brand new session.
+
+=head2 is\_expired()
+
+Tests whether session initialized using L&lt;load()|/"load"&gt; is to be expired. This method works only on sessions initialized with load():
+
+$s = CGI::Session-&gt;load() or die CGI::Session-&gt;errstr; if ( $s-&gt;is\_expired ) \{ die "Your session expired. Please refresh"; \} if ( $s-&gt;is\_empty ) \{ $s = $s-&gt;new() or die $s-&gt;errstr; \}
+
+=head2 is\_empty()
+
+Returns true for sessions that are empty. It's preferred way of testing whether requested session was loaded successfully or not:
+
+$s = CGI::Session-&gt;load($sid); if ( $s-&gt;is\_empty ) \{ $s = $s-&gt;new(); \}
+
+Actually, the above code is nothing but waste. The same effect could've been achieved by saying:
+
+$s = CGI::Session-&gt;new( $sid );
+
+L&lt;is\_empty()|/"is\_empty"&gt; is useful only if you wanted to catch requests for expired sessions, and create new session afterwards. See L&lt;is\_expired()|/"is\_expired"&gt; for an example.
+
+=head2 delete()
+
+Deletes a session from the data store and empties session data from memory, completely, so subsequent read/write requests on the same object will fail. Technically speaking, it will only set object's status to I and will trigger L&lt;flush()|/"flush"&gt;, and flush() will do the actual removal.
+
+=head2 find( \\&amp;code )
+
+=head2 find( $dsn, \\&amp;code )
+
+=head2 find( $dsn, \\&amp;code, \\%dsn\_args )
+
+Experimental feature. Executes \\&amp;code for every session object stored in disk, passing initialized CGI::Session object as the first argument of \\&amp;code. Useful for housekeeping purposes, such as for removing expired sessions. Following line, for instance, will remove sessions already expired, but are still in disk:
+
+The following line, for instance, will remove sessions already expired, but which are still on disk:
+
+CGI::Session-&gt;find( sub \{\} );
+
+Notice, above \\&amp;code didn't have to do anything, because load(), which is called to initialize sessions inside find(), will automatically remove expired sessions. Following example will remove all the objects that are 10+ days old:
+
+CGI::Session-&gt;find( \\&amp;purge ); sub purge \{ my ($session) = @\_; next if $session-&gt;is\_empty; # &lt;-- already expired?! if ( ($session-&gt;ctime + 3600\*240) &lt;= time() ) \{ $session-&gt;delete() or warn "couldn't remove " . $session-&gt;id . ": " . $session-&gt;errstr; \} \}
+
+B: find will not change the modification or access times on the sessions it returns.
+
+Explanation of the 3 parameters to C&lt;find()&gt;:
+
+=over 4
+
+=item $dsn
+
+This is the DSN (Data Source Name) used by CGI::Session to control what type of sessions you previously created and what type of sessions you now wish method C&lt;find()&gt; to pass to your callback.
+
+The default value is defined above, in the docs for method C&lt;new()&gt;, and is 'driver:file;serializer:default;id:md5'.
+
+Do not confuse this DSN with the DSN arguments mentioned just below, under \\%dsn\_args.
+
+=item \\&amp;code
+
+This is the callback provided by you (i.e. the caller of method C&lt;find()&gt;) which is called by CGI::Session once for each session found by method C&lt;find()&gt; which matches the given $dsn.
+
+There is no default value for this coderef.
+
+When your callback is actually called, the only parameter is a session. If you want to call a subroutine you already have with more parameters, you can achieve this by creating an anonymous subroutine that calls your subroutine with the parameters you want. For example:
+
+CGI::Session-&gt;find($dsn, sub \{ my\_subroutine( @\_, 'param 1', 'param 2' ) \} ); CGI::Session-&gt;find($dsn, sub \{ $coderef-&gt;( @\_, $extra\_arg ) \} );
+
+Or if you wish, you can define a sub generator as such:
+
+sub coderef\_with\_args \{ my ( $coderef, @params ) = @\_; return sub \{ $coderef-&gt;( @\_, @params ) \}; \}
+
+CGI::Session-&gt;find($dsn, coderef\_with\_args( $coderef, 'param 1', 'param 2' ) );
+
+=item \\%dsn\_args
+
+If your $dsn uses file-based storage, then this hashref might contain keys such as:
+
+\{ Directory =&gt; Value 1, [[NoFlock]] =&gt; Value 2, UMask =&gt; Value 3 \}
+
+If your $dsn uses db-based storage, then this hashref contains (up to) 3 keys, and looks like:
+
+\{ [[DataSource]] =&gt; Value 1, User =&gt; Value 2, Password =&gt; Value 3 \}
+
+These 3 form the DSN, username and password used by DBI to control access to your database server, and hence are only relevant when using db-based sessions.
+
+The default value of this hashref is undef.
+
+=back
+
+B&lt;Note:&gt; find() is meant to be convenient, not necessarily efficient. It's best suited in cron scripts.
+
+=head1 MISCELLANEOUS METHODS
+
+=head2 remote\_addr()
+
+Returns the remote address of the user who created the session for the first time. Returns undef if variable REMOTE\_ADDR wasn't present in the environment when the session was created.
+
+=head2 errstr()
+
+Class method. Returns last error message from the library.
+
+=head2 dump()
+
+Returns a dump of the session object. Useful for debugging purposes only.
+
+=head2 header()
+
+Replacement for L&lt;CGI.pm|CGI&gt;'s header() method. Without this method, you usually need to create a CGI::Cookie object and send it as part of the HTTP header:
+
+$cookie = CGI::Cookie-&gt;new(-name=&gt;$session-&gt;name, -value=&gt;$session-&gt;id); print $cgi-&gt;header(-cookie=&gt;$cookie);
+
+You can minimize the above into:
+
+print $session-&gt;header();
+
+It will retrieve the name of the session cookie from C&lt;$session-&gt;name()&gt; which defaults to C&lt;$CGI::Session::NAME&gt;. If you want to use a different name for your session cookie, do something like following before creating session object:
+
+CGI::Session-&gt;name("MY\_SID"); $session = new CGI::Session(undef, $cgi, \\%attrs);
+
+Now, $session-&gt;header() uses "MY\_SID" as a name for the session cookie.
+
+=head2 query()
+
+Returns query object associated with current session object. Default query object class is L&lt;CGI.pm|CGI&gt;.
+
+=head2 DEPRECATED METHODS
+
+These methods exist solely for for compatibility with CGI::Session 3.x.
+
+=head3 close()
+
+Closes the session. Using flush() is recommended instead, since that's exactly what a call to close() does now.
+
+=head1 DISTRIBUTION
+
+CGI::Session consists of several components such as L&lt;drivers|"DRIVERS"&gt;, L&lt;serializers|"SERIALIZERS"&gt; and L. This section lists what is available.
+
+=head2 DRIVERS
+
+Following drivers are included in the standard distribution:
+
+=over 4
+
+=item \*
+
+L&lt;file|CGI::Session::Driver::file&gt; - default driver for storing session data in plain files. Full name: B&lt;CGI::Session::Driver::file&gt;
+
+=item \*
+
+L&lt;db\_file|CGI::Session::Driver::db\_file&gt; - for storing session data in [[BerkelyDB]]. Requires: L. Full name: B&lt;CGI::Session::Driver::db\_file&gt;
+
+=item \*
+
+L&lt;mysql|CGI::Session::Driver::mysql&gt; - for storing session data in [[MySQL]] tables. Requires L&lt;DBI|DBI&gt; and L&lt;DBD::mysql|DBD::mysql&gt;. Full name: B&lt;CGI::Session::Driver::mysql&gt;
+
+=item \*
+
+L&lt;sqlite|CGI::Session::Driver::sqlite&gt; - for storing session data in SQLite. Requires L&lt;DBI|DBI&gt; and L&lt;DBD::SQLite|DBD::SQLite&gt;. Full name: B&lt;CGI::Session::Driver::sqlite&gt;
+
+=back
+
+=head2 SERIALIZERS
+
+=over 4
+
+=item \*
+
+L&lt;default|CGI::Session::Serialize::default&gt; - default data serializer. Uses standard L&lt;Data::Dumper|Data::Dumper&gt;. Full name: B&lt;CGI::Session::Serialize::default&gt;.
+
+=item \*
+
+L&lt;storable|CGI::Session::Serialize::storable&gt; - serializes data using L. Requires L. Full name: B&lt;CGI::Session::Serialize::storable&gt;.
+
+=item \*
+
+L&lt;freezethaw|CGI::Session::Serialize::freezethaw&gt; - serializes data using L. Requires L. Full name: B&lt;CGI::Session::Serialize::freezethaw&gt;
+
+=item \*
+
+L&lt;yaml|CGI::Session::Serialize::yaml&gt; - serializes data using YAML. Requires L or L&lt;YAML::Syck&gt;. Full name: B&lt;CGI::Session::Serialize::yaml&gt;
+
+=item \*
+
+L&lt;json|CGI::Session::Serialize::json&gt; - serializes data using JSON. Requires L&lt;JSON::Syck&gt;. Full name: B&lt;CGI::Session::Serialize::json&gt;
+
+=back
+
+=head2 ID GENERATORS
+
+Following ID generators are available:
+
+=over 4
+
+=item \*
+
+L&lt;md5|CGI::Session::ID::md5&gt; - generates 32 character long hexadecimal string. Requires L&lt;Digest::MD5|Digest::MD5&gt;. Full name: B&lt;CGI::Session::ID::md5&gt;.
+
+=item \*
+
+L&lt;incr|CGI::Session::ID::incr&gt; - generates incremental session ids.
+
+=item \*
+
+L&lt;static|CGI::Session::ID::static&gt; - generates static session ids. B&lt;CGI::Session::ID::static&gt;
+
+=back
+
+=head1 CREDITS
+
+CGI::Session evolved to what it is today with the help of following developers. The list doesn't follow any strict order, but somewhat chronological. Specifics can be found in F file
+
+=over 4
+
+=item Andy Lester
+
+=item Brian King Emrbbking@mac.comE
+
+=item Olivier Dragon Edragon@shadnet.shad.caE
+
+=item Adam Jacob Eadam@sysadminsith.orgE
+
+=item Igor Plisco Eigor@plisco.ruE
+
+=item Mark Stosberg
+
+=item Matt [[LeBlanc]] Emleblanc@cpan.orgE
+
+=item Shawn Sorichetti
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright (C) 2001-2005 Sherzod Ruzmetov Esherzodr@cpan.orgE. All rights reserved. This library is free software. You can modify and or distribute it under the same terms as Perl itself.
+
+=head1 PUBLIC CODE REPOSITORY
+
+You can see what the developers have been up to since the last release by checking out the code repository. You can browse the Subversion repository from here:
+
+<http://svn.cromedome.net/>
+
+Or check it directly with C from here:
+
+svn://svn.cromedome.net/CGI-Session
+
+=head1 SUPPORT
+
+If you need help using CGI::Session consider the mailing list. You can ask the list by sending your questions to <cgi-session-user@lists.sourceforge.net> .
+
+You can subscribe to the mailing list at <https://lists.sourceforge.net/lists/listinfo/cgi-session-user> .
+
+Bug reports can be submitted at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Session>
+
+=head1 AUTHOR
+
+Sherzod Ruzmetov Esherzodr@cpan.orgE, <http://author.handalak.com/>
+
+Mark Stosberg became a co-maintainer during the development of 4.0. C&lt;markstos@cpan.org&gt;.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item \*
+
+L&lt;CGI::Session::Tutorial|CGI::Session::Tutorial&gt; - extended CGI::Session manual
+
+=item \*
+
+B - "HTTP State Management Mechanism" found at <ftp://ftp.isi.edu/in-notes/rfc2965.txt>
+
+=item \*
+
+L&lt;CGI|CGI&gt; - standard CGI library
+
+=item \*
+
+L&lt;Apache::Session|Apache::Session&gt; - another fine alternative to CGI::Session
+
+=back
diff --git a/TWiki/CGISessionDriverDBIDotPm.mdwn b/TWiki/CGISessionDriverDBIDotPm.mdwn
new file mode 100644 (file)
index 0000000..242d9f9
--- /dev/null
@@ -0,0 +1,67 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver::DBI - Base class for native DBI-related CGI::Session drivers
+
+=head1 SYNOPSIS
+
+require CGI::Session::Driver::DBI; @ISA = qw( CGI::Session::Driver::DBI );
+
+=head1 DESCRIPTION
+
+In most cases you can create a new DBI-driven CGI::Session driver by simply creating an empty driver file that inherits from CGI::Session::Driver::DBI. That's exactly what L&lt;sqlite|CGI::Session::Driver::sqlite&gt; does. The only reason why this class doesn't suit for a valid driver is its name isn't in lowercase. I'm serious!
+
+=head2 NOTES
+
+CGI::Session::Driver::DBI defines init() method, which makes DBI handle available for drivers in I - object attribute regardless of what C&lt;\\%dsn\_args&gt; were used in creating session object. Should your driver require non-standard initialization you have to re-define init() method in your F&lt;.pm&gt; file, but make sure to set 'Handle' - object attribute to database handle (returned by DBI-&gt;connect(...)) if you wish to inherit any of the methods from CGI::Session::Driver::DBI.
+
+=head1 STORAGE
+
+Before you can use any DBI-based session drivers you need to make sure compatible database table is created for CGI::Session to work with. Following command will produce minimal requirements in most SQL databases:
+
+CREATE TABLE sessions ( id CHAR(32) NOT NULL PRIMARY KEY, a\_session TEXT NOT NULL );
+
+Your session table can define additional columns, but the above two are required. Name of the session table is expected to be I by default. You may use a different name if you wish. To do this you have to pass I as part of your C&lt; \\%dsn\_args &gt;:
+
+$s = new CGI::Session("driver:sqlite", undef, \{TableName=&gt;'my\_sessions'\}); $s = new CGI::Session("driver:mysql", undef, \{ [[TableName]]=&gt;'my\_sessions', [[DataSource]]=&gt;'dbi:mysql:shopping\_cart'\});
+
+=head1 DRIVER ARGUMENTS
+
+Following driver arguments are supported:
+
+=over 4
+
+=item [[DataSource]]
+
+First argument to be passed to L&lt;DBI|DBI&gt;-&gt;L&lt;connect()|DBI/connect()&gt;. If the driver makes the database connection itself, it will also explicitly disconnect from the database when the driver object is DESTROYed.
+
+=item User
+
+User privileged to connect to the database defined in C.
+
+=item Password
+
+Password of the I privileged to connect to the database defined in C
+
+=item Handle
+
+An existing L database handle object. The handle can be created on demand by providing a code reference as a argument, such as C&lt;&lt;sub\{DBI-&gt;connect\}&gt;&gt;. This way, the database connection is only created if it actually needed. This can be useful when combined with a framework plugin like L&lt;CGI::Application::Plugin::Session&gt;, which creates a CGI::Session object on demand as well.
+
+C will override all the above arguments, if any present.
+
+=item [[TableName]]
+
+Name of the table session data will be stored in.
+
+=back
+
+=head1 LICENSING
+
+For support and licensing information see L&lt;CGI::Session|CGI::Session&gt;
diff --git a/TWiki/CGISessionDriverDb_fileDotPm.mdwn b/TWiki/CGISessionDriverDb_fileDotPm.mdwn
new file mode 100644 (file)
index 0000000..8897b99
--- /dev/null
@@ -0,0 +1,27 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver::db\_file - CGI::Session driver for [[BerkeleyDB]] using DB\_File
+
+=head1 SYNOPSIS
+
+$s = new CGI::Session("driver:db\_file", $sid); $s = new CGI::Session("driver:db\_file", $sid, \{FileName=&gt;'/tmp/cgisessions.db'\});
+
+=head1 DESCRIPTION
+
+B stores session data in [[BerkelyDB]] file using L&lt;DB\_File|DB\_File&gt; - Perl module. All sessions will be stored in a single file, specified in I driver argument as in the above example. If I isn't given, defaults to F&lt;/tmp/cgisess.db&gt;, or its equivalent on a non-UNIX system.
+
+If the directory hierarchy leading to the file does not exist, will be created for you.
+
+This module takes a B option which will be used if DB\_File has to create the database file for you. By default the umask is 0660.
+
+=head1 LICENSING
+
+For support and licensing information see L&lt;CGI::Session|CGI::Session&gt;
diff --git a/TWiki/CGISessionDriverDotPm.mdwn b/TWiki/CGISessionDriverDotPm.mdwn
new file mode 100644 (file)
index 0000000..92d54cd
--- /dev/null
@@ -0,0 +1,123 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+**extends** `CGI::Session::ErrorHandler`
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver - CGI::Session driver specifications
+
+=head1 WARNING
+
+Version 4.0 of CGI::Session's driver specification is B backward compatible with previous specification. If you already have a driver developed to work with the previous version you're highly encouraged to upgrade your driver code to make it compatible with the current version. Fortunately, current driver specs are a lot easier to adapt to.
+
+If you need any help converting your driver to meet current specs, send me an e-mail. For support information see L&lt;CGI::Session|CGI::Session&gt;
+
+=head1 SYNOPSIS
+
+require CGI::Session::Driver; @ISA = qw( CGI::Session::Driver );
+
+=head1 DESCRIPTION
+
+CGI::Session::Driver is a base class for all CGI::Session's native drivers. It also documents driver specifications for those willing to write drivers for different databases not currently supported by CGI::Session.
+
+=head1 WHAT IS A DRIVER
+
+Driver is a piece of code that helps CGI::Session library to talk to specific database engines, or storage mechanisms. To be more precise, driver is a F&lt;.pm&gt; file that inherits from CGI::Session::Driver and defines L&lt;retrieve()|/"retrieve($self, $sid)"&gt;, L&lt;store()|/"store($self, $sid, $datastr)"&gt; and L&lt;remove()|/"remove($self, $sid)"&gt; methods.
+
+=head2 BLUEPRINT
+
+The best way of learning the specs is to look at a blueprint of a driver:
+
+package CGI::Session::Driver::your\_driver\_name; use strict; use base qw( CGI::Session::Driver CGI::Session::ErrorHandler );
+
+sub init \{ my ($self) = @\_; # optional \}
+
+sub DESTROY \{ my ($self) = @\_; # optional \}
+
+sub store \{ my ($self, $sid, $datastr) = @\_; # Store $datastr, which is an already serialized string of data. \}
+
+sub retrieve \{ my ($self, $sid) = @\_; # Return $datastr, which was previously stored using above store() method. # Return $datastr if $sid was found. Return 0 or "" if $sid doesn't exist \}
+
+sub remove \{ my ($self, $sid) = @\_; # Remove storage associated with $sid. Return any true value indicating success, # or undef on failure. \}
+
+sub traverse \{ my ($self, $coderef) = @\_; # execute $coderef for each session id passing session id as the first and the only # argument \}
+
+1;
+
+All the attributes passed as the second argument to CGI::Session's new() or load() methods will automatically be made driver's object attributes. For example, if session object was initialized as following:
+
+$s = CGI::Session-&gt;new("driver:your\_driver\_name", undef, \{Directory=&gt;'/tmp/sessions'\});
+
+You can access value of 'Directory' from within your driver like so:
+
+sub store \{ my ($self, $sid, $datastr) = @\_; my $dir = $self-&gt;\{Directory\}; # &lt;-- in this example will be '/tmp/sessions' \}
+
+Optionally, you can define C&lt;init()&gt; method within your driver to do driver specific global initialization. C&lt;init()&gt; method will be invoked only once during the lifecycle of your driver, which is the same as the lifecycle of a session object.
+
+For examples of C&lt;init()&gt; look into the source code of native CGI::Session drivers.
+
+=head1 METHODS
+
+This section lists and describes all driver methods. All the driver methods will receive driver object ($self) as the first argument. Methods that pertain to an individual session (such as C&lt;retrieve()&gt;, C&lt;store()&gt; and C&lt;remove()&gt;) will also receive session id ($sid) as the second argument.
+
+Following list describes every driver method, including its argument list and what step of session's life they will be invoked. Understanding this may help driver authors.
+
+=over 4
+
+=item retrieve($self, $sid)
+
+Called whenever a specific session is requested either via C&lt;&lt; CGI::Session-&gt;new() &gt;&gt; or C&lt;&lt; CGI::Session-&gt;load() &gt;&gt; syntax. Method should try to retrieve data associated with C&lt; $sid &gt; and return it. In case no data could be retrieved for C&lt; $sid &gt; 0 (zero) or "" should be returned. undef must be returned only to signal error. Error message should be set via set\_error(), which can be inherited from L&lt;CGI::Session::ErrorHandler|CGI::Session::ErrorHandler&gt;.
+
+Tip: set\_error() always returns undef. Use it for your advantage.
+
+=item store($self, $sid, $datastr)
+
+Called whenever modified session data is to be stored back to disk. This happens whenever CGI::Session-&gt;flush() is called on modified session. Since CGI::Session-&gt;DESTROY() calls flush(), store() gets requested each time session object is to be terminated.
+
+C&lt; store() &gt; is called both to store new sessions and to update already stored sessions. It's driver author's job to figure out which operation needs to be performed.
+
+$datastr, which is passed as the third argument to represents B session data that needs to be saved.
+
+store() can return any true value indicating success or undef on failure. Error message should be passed to set\_error()
+
+=item remove($self, $sid)
+
+Called whenever session data is to be deleted, which is when CGI::Session-&gt;delete() is called. Should return any true value indicating success, undef on failure. Error message should be logged in set\_error().
+
+=item traverse($self, \\&amp;coderef)
+
+Called only from within CGI::Session-&gt;find(). Job of traverse() is to call \\&amp;coderef for every single session stored in disk passing session's id as the first and only argument: C&lt;&lt; $coderef-&gt;( $sid ) &gt;&gt;
+
+=item init($self)
+
+Optional. Called whenever driver object is to be initialized, which happens only once during the lifecycle of CGI::Session object. Here you can do driver-wide initialization, such as to open connection to a database server.
+
+=item DESTROY($self)
+
+Optional. Perl automatically calls this method on objects just before they are to be terminated. This gives your driver chance to close any database connections or close any open file handles.
+
+=back
+
+=head2 NOTES
+
+=over 4
+
+=item \*
+
+All driver F&lt;.pm&gt; files must be lowercase!
+
+=item \*
+
+DBI-related drivers are better off using L&lt;CGI::Session::Driver::DBI|CGI::Session::Driver::DBI&gt; as base, but don't have to.
+
+=back
+
+=head1 LICENSING
+
+For support and licensing see L&lt;CGI::Session|CGI::Session&gt;.
diff --git a/TWiki/CGISessionDriverFileDotPm.mdwn b/TWiki/CGISessionDriverFileDotPm.mdwn
new file mode 100644 (file)
index 0000000..afc6eb8
--- /dev/null
@@ -0,0 +1,41 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver::file - Default CGI::Session driver
+
+=head1 SYNOPSIS
+
+$s = new CGI::Session(); $s = new CGI::Session("driver:file", $sid); $s = new CGI::Session("driver:file", $sid, \{Directory=&gt;'/tmp'\});
+
+=head1 DESCRIPTION
+
+When CGI::Session object is created without explicitly setting I, I will be assumed. I - driver will store session data in plain files, where each session will be stored in a separate file.
+
+Naming conventions of session files are defined by C&lt;$CGI::Session::Driver::file::FileName&gt; global variable. Default value of this variable is I&lt;cgisess\_%s&gt;, where %s will be replaced with respective session ID. Should you wish to set your own [[FileName]] template, do so before requesting for session object:
+
+$CGI::Session::Driver::file::FileName = "%s.dat"; $s = new CGI::Session();
+
+For backwards compatibility with 3.x, you can also use the variable name C&lt;$CGI::Session::File::FileName&gt;, which will override the one above.
+
+=head2 DRIVER ARGUMENTS
+
+If you wish to specify a session directory, use the B option, which denotes location of the directory where session ids are to be kept. If B is not set, defaults to whatever File::Spec-&gt;tmpdir() returns. So all the three lines in the SYNOPSIS section of this manual produce the same result on a UNIX machine.
+
+If specified B does not exist, all necessary directory hierarchy will be created.
+
+By default, sessions are created with a umask of 0660. If you wish to change the umask for a session, pass a B option with an octal representation of the umask you would like for said session.
+
+=head1 NOTES
+
+If your OS doesn't support flock, you should understand the risks of going without locking the session files. Since sessions tend to be used in environments where race conditions may occur due to concurrent access of files by different processes, locking tends to be seen as a good and very necessary thing. If you still want to use this driver but don't want flock, set C&lt;$CGI::Session::Driver::file::NoFlock&gt; to 1 or pass C&lt;&lt; [[NoFlock]] =&gt; 1 &gt;&gt; and this driver will operate without locks.
+
+=head1 LICENSING
+
+For support and licensing see L&lt;CGI::Session|CGI::Session&gt;
diff --git a/TWiki/CGISessionDriverMysqlDotPm.mdwn b/TWiki/CGISessionDriverMysqlDotPm.mdwn
new file mode 100644 (file)
index 0000000..f7c4158
--- /dev/null
@@ -0,0 +1,41 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+**extends** `CGI::Session::Driver::DBI `
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver::mysql - CGI::Session driver for [[MySQL]] database
+
+=head1 SYNOPSIS
+
+$s = new CGI::Session( "driver:mysql", $sid); $s = new CGI::Session( "driver:mysql", $sid, \{ [[DataSource]] =&gt; 'dbi:mysql:test', User =&gt; 'sherzodr', Password =&gt; 'hello' \}); $s = new CGI::Session( "driver:mysql", $sid, \{ Handle =&gt; $dbh \} );
+
+=head1 DESCRIPTION
+
+B stores session records in a [[MySQL]] table. For details see L&lt;CGI::Session::Driver::DBI|CGI::Session::Driver::DBI&gt;, its parent class.
+
+It's especially important for the [[MySQL]] driver that the session ID column be defined as a primary key, or at least "unique", like this:
+
+CREATE TABLE sessions ( id CHAR(32) NOT NULL PRIMARY KEY, a\_session TEXT NOT NULL );
+
+=head2 DRIVER ARGUMENTS
+
+B driver supports all the arguments documented in L&lt;CGI::Session::Driver::DBI|CGI::Session::Driver::DBI&gt;. In addition, I argument can optionally leave leading "dbi:mysql:" string out:
+
+$s = new CGI::Session( "driver:mysql", $sid, \{DataSource=&gt;'shopping\_cart'\}); # is the same as: $s = new CGI::Session( "driver:mysql", $sid, \{DataSource=&gt;'dbi:mysql:shopping\_cart'\});
+
+=head2 BACKWARDS COMPATIBILITY
+
+For backwards compatibility, you can also set the table like this before calling C&lt;new()&gt;. However, it is not recommended because it can cause conflicts in a persistent environment.
+
+$CGI::Session::MySQL::TABLE\_NAME = 'my\_sessions';
+
+=head1 LICENSING
+
+For support and licensing see L&lt;CGI::Session|CGI::Session&gt;.
diff --git a/TWiki/CGISessionDriverPostgresqlDotPm.mdwn b/TWiki/CGISessionDriverPostgresqlDotPm.mdwn
new file mode 100644 (file)
index 0000000..b91bf7d
--- /dev/null
@@ -0,0 +1,51 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+**extends** `CGI::Session::Driver::DBI `
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver::postgresql - [[PostgreSQL]] driver for CGI::Session
+
+=head1 SYNOPSIS
+
+use CGI::Session; $session = new CGI::Session("driver:PostgreSQL", undef, \{Handle=&gt;$dbh\});
+
+=head1 DESCRIPTION
+
+CGI::Session::PostgreSQL is a L&lt;CGI::Session|CGI::Session&gt; driver to store session data in a [[PostgreSQL]] table.
+
+=head1 STORAGE
+
+Before you can use any DBI-based session drivers you need to make sure compatible database table is created for CGI::Session to work with. Following command will produce minimal requirements in most SQL databases:
+
+CREATE TABLE sessions ( id CHAR(32) NOT NULL PRIMARY KEY, a\_session BYTEA NOT NULL );
+
+and within your code use:
+
+use CGI::Session; $session = new CGI::Session("driver:PostgreSQL", undef, \{Handle=&gt;$dbh, [[ColumnType]]=&gt;"binary"\});
+
+Please note the I argument. [[PostgreSQL]]'s text type has problems when trying to hold a null character. (Known as C&lt;"\\0"&gt; in Perl, not to be confused with SQL I). If you know there is no chance of ever having a null character in the serialized data, you can leave off the I attribute. Using a I column type and C&lt;&lt; [[ColumnType]] =&gt; 'binary' &gt;&gt; is recommended when using L&lt;Storable|CGI::Session::Serialize::storable&gt; as the serializer or if there's any possibility that a null value will appear in any of the serialized data.
+
+For more details see L&lt;CGI::Session::Driver::DBI|CGI::Session::Driver::DBI&gt;, parent class.
+
+Also see L, which exercises different method for dealing with binary data.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2002 Cosimo Streppone. All rights reserved. This library is free software and can be modified and distributed under the same terms as Perl itself.
+
+=head1 AUTHORS
+
+Cosimo Streppone &lt;cosimo@cpan.org&gt;, heavily based on the CGI::Session::MySQL driver by Sherzod Ruzmetov, original author of CGI::Session.
+
+Matt [[LeBlanc]] contributed significant updates for the 4.0 release.
+
+=head1 LICENSING
+
+For additional support and licensing see L&lt;CGI::Session|CGI::Session&gt;
diff --git a/TWiki/CGISessionDriverSqliteDotPm.mdwn b/TWiki/CGISessionDriverSqliteDotPm.mdwn
new file mode 100644 (file)
index 0000000..2a391fe
--- /dev/null
@@ -0,0 +1,35 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver::sqlite - CGI::Session driver for SQLite
+
+=head1 SYNOPSIS
+
+$s = new CGI::Session("driver:sqlite", $sid, \{DataSource=&gt;'/my/folder/sessions.sqlt'\}); $s = new CGI::Session("driver:sqlite", $sid, \{Handle=&gt;$dbh\});
+
+=head1 DESCRIPTION
+
+B driver stores session data in SQLite files using L&lt;DBD::SQLite|DBD::SQLite&gt; DBI driver. More details see L&lt;CGI::Session::Driver::DBI|CGI::Session::Driver::DBI&gt;, its parent class.
+
+=head1 DRIVER ARGUMENTS
+
+Supported driver arguments are I and I. B only one of these arguments can be set while creating session object.
+
+I should be in the form of C&lt;dbi:SQLite:dbname=/path/to/db.sqlt&gt;. If C&lt;dbi:SQLite:&gt; is missing it will be prepended for you. If I is present it should be database handle (C&lt;$dbh&gt;) returned by L&lt;DBI::connect()|DBI/connect()&gt;.
+
+As of version 1.7 of this driver, the third argument is B optional. Using a default database in the temporary directory is a security risk since anyone on the machine can create and/or read your session data. If you understand these risks and still want the old behavior, you can set the C option to I&lt;'/tmp/sessions.sqlt'&gt;.
+
+=head1 BUGS AND LIMITATIONS
+
+None known.
+
+=head1 LICENSING
+
+For support and licensing see L&lt;CGI::Session|CGI::Session&gt;
diff --git a/TWiki/CGISessionErrorHandlerDotPm.mdwn b/TWiki/CGISessionErrorHandlerDotPm.mdwn
new file mode 100644 (file)
index 0000000..cfcd0ee
--- /dev/null
@@ -0,0 +1,29 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::ErrorHandler - error handling routines for CGI::Session
+
+=head1 SYNOPSIS
+
+require CGI::Session::ErrorHandler @ISA = qw( CGI::Session::ErrorHandler );
+
+sub some\_method \{ my $self = shift; unless ( $some\_condition ) \{ return $self-&gt;set\_error("some\_method(): \\$some\_condition isn't met"); \} \}
+
+=head1 DESCRIPTION
+
+CGI::Session::ErrorHandler provides set\_error() and errstr() methods for setting and accessing error messages from within CGI::Session's components. This method should be used by driver developers for providing CGI::Session-standard error handling routines for their code
+
+=head2 METHODS
+
+=over 4
+
+=item set\_error($message)
+
+Implicitly defines $pkg\_name::errstr and sets its value to $message. Return value is B undef.
diff --git a/TWiki/CGISessionIDIncrDotPm.mdwn b/TWiki/CGISessionIDIncrDotPm.mdwn
new file mode 100644 (file)
index 0000000..414d43d
--- /dev/null
@@ -0,0 +1,41 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+**extends** `CGI::Session::ErrorHandler `
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::ID::incr - CGI::Session ID driver
+
+=head1 SYNOPSIS
+
+use CGI::Session; $session = new CGI::Session("id:Incr", undef, \{ Directory =&gt; '/tmp', IDFile =&gt; '/tmp/cgisession.id', IDInit =&gt; 1000, IDIncr =&gt; 2 \});
+
+=head1 DESCRIPTION
+
+CGI::Session::ID::incr is to generate auto incrementing Session IDs. Compare it with L&lt;CGI::Session::ID::md5|CGI::Session::ID::md5&gt;, where session ids are truly random 32 character long strings. CGI::Session::ID::incr expects the following arguments passed to CGI::Session-&gt;new() as the third argument.
+
+=over 4
+
+=item IDFile
+
+Location where auto incremented IDs are stored. This attribute is required.
+
+=item IDInit
+
+Initial value of the ID if it's the first ID to be generated. For example, if you want the ID numbers to start with 1000 as opposed to 0, that's where you should set your value. Default is C&lt;0&gt;.
+
+=item IDIncr
+
+How many digits each number should increment by. For example, if you want the first generated id to start with 1000, and each subsequent id to increment by 10, set I to 10 and I to 1000. Default is C&lt;1&gt;.
+
+=back
+
+=head1 LICENSING
+
+For support and licensing information see L&lt;CGI::Session|CGI::Session&gt;
diff --git a/TWiki/CGISessionIDMd5DotPm.mdwn b/TWiki/CGISessionIDMd5DotPm.mdwn
new file mode 100644 (file)
index 0000000..61d3d27
--- /dev/null
@@ -0,0 +1,25 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+**extends** `CGI::Session::ErrorHandler `
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::ID::md5 - default CGI::Session ID generator
+
+=head1 SYNOPSIS
+
+use CGI::Session; $s = new CGI::Session("id:md5", undef);
+
+=head1 DESCRIPTION
+
+CGI::Session::ID::MD5 is to generate MD5 encoded hexadecimal random ids. The library does not require any arguments.
+
+=head1 LICENSING
+
+For support and licensing see L&lt;CGI::Session|CGI::Session&gt;
diff --git a/TWiki/CGISessionSerializeDefaultDotPm.mdwn b/TWiki/CGISessionSerializeDefaultDotPm.mdwn
new file mode 100644 (file)
index 0000000..f3ebe60
--- /dev/null
@@ -0,0 +1,35 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Serialize::default - Default CGI::Session serializer
+
+=head1 DESCRIPTION
+
+This library is used by CGI::Session driver to serialize session data before storing it in disk.
+
+All the methods are called as class methods.
+
+=head1 METHODS
+
+=over 4
+
+=item freeze($class, \\%hash)
+
+Receives two arguments. First is the class name, the second is the data to be serialized. Should return serialized string on success, undef on failure. Error message should be set using C&lt;set\_error()|CGI::Session::ErrorHandler/"set\_error()"&gt;
+
+=item thaw($class, $string)
+
+Received two arguments. First is the class name, second is the I data string. Should return thawed data structure on success, undef on failure. Error message should be set using C&lt;set\_error()|CGI::Session::ErrorHandler/"set\_error()"&gt;
+
+=back
+
+=head1 LICENSING
+
+For support and licensing see L&lt;CGI::Session|CGI::Session&gt;
diff --git a/TWiki/CGISessionSerializeFreezethawDotPm.mdwn b/TWiki/CGISessionSerializeFreezethawDotPm.mdwn
new file mode 100644 (file)
index 0000000..1a24994
--- /dev/null
@@ -0,0 +1,33 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Serialize::freezethaw - serializer for CGI::Session
+
+=head1 DESCRIPTION
+
+This library can be used by CGI::Session to serialize session data. Uses L&lt;FreezeThaw|FreezeThaw&gt;.
+
+=head1 METHODS
+
+=over 4
+
+=item freeze($class, \\%hash)
+
+Receives two arguments. First is the class name, the second is the data to be serialized. Should return serialized string on success, undef on failure. Error message should be set using C&lt;set\_error()|CGI::Session::ErrorHandler/"set\_error()"&gt;
+
+=item thaw($class, $string)
+
+Received two arguments. First is the class name, second is the I data string. Should return thawed data structure on success, undef on failure. Error message should be set using C&lt;set\_error()|CGI::Session::ErrorHandler/"set\_error()"&gt;
+
+=back
+
+=head1 LICENSING
+
+For support and licensing see L&lt;CGI::Session|CGI::Session&gt;
diff --git a/TWiki/CGISessionSerializeJsonDotPm.mdwn b/TWiki/CGISessionSerializeJsonDotPm.mdwn
new file mode 100644 (file)
index 0000000..a7b4376
--- /dev/null
@@ -0,0 +1,33 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Serialize::json - serializer for CGI::Session
+
+=head1 DESCRIPTION
+
+This library can be used by CGI::Session to serialize session data. Requires L&lt;JSON::Syck|JSON::Syck&gt;. JSON is a type of L&lt;YAML|CGI::Session::Serialize::yaml&gt;, with one extension: serialized JSON strings are actually valid [[JavaScript]] code that a browser can execute. Any langauge that has a YAML parser (Perl, PHP, Python, Ruby, C, etc) can also read data that has been serialized with JSON.
+
+=head1 METHODS
+
+=over 4
+
+=item freeze($class, \\%hash)
+
+Receives two arguments. First is the class name, the second is the data to be serialized. Should return serialized string on success, undef on failure. Error message should be set using C&lt;set\_error()|CGI::Session::ErrorHandler/"set\_error()"&gt;
+
+=item thaw($class, $string)
+
+Received two arguments. First is the class name, second is the I data string. Should return thawed data structure on success, undef on failure. Error message should be set using C&lt;set\_error()|CGI::Session::ErrorHandler/"set\_error()"&gt;
+
+=back
+
+=head1 SEE ALSO
+
+L&lt;CGI::Session&gt;, L&lt;JSON::Syck&gt;.
diff --git a/TWiki/CGISessionSerializeStorableDotPm.mdwn b/TWiki/CGISessionSerializeStorableDotPm.mdwn
new file mode 100644 (file)
index 0000000..674675c
--- /dev/null
@@ -0,0 +1,23 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Serialize::storable - Serializer for CGI::Session
+
+=head1 DESCRIPTION
+
+This library can be used by CGI::Session to serialize session data. Uses L&lt;Storable|Storable&gt;.
+
+=head1 METHODS
+
+=over 4
+
+=item freeze($class, \\%hash)
+
+Receives two arguments. First is the class name, the second is the data to be serialized. Should return serialized string on success, undef on failure. Error message should be set using C&lt;set\_error()|CGI::Session::ErrorHandler/"set\_error()"&gt;
diff --git a/TWiki/CGISessionSerializeYamlDotPm.mdwn b/TWiki/CGISessionSerializeYamlDotPm.mdwn
new file mode 100644 (file)
index 0000000..67d0382
--- /dev/null
@@ -0,0 +1,35 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Serialize::yaml - serializer for CGI::Session
+
+=head1 DESCRIPTION
+
+This library can be used by CGI::Session to serialize session data. It uses L&lt;YAML|YAML&gt;, or the faster C implementation, L&lt;YAML::Syck|YAML::Syck&gt; if it is available. YAML serializers exist not just for Perl but also other dynamic languages, such as PHP, Python, and Ruby, so storing session data in this format makes it easy to share session data across different languages.
+
+YAML is made to be friendly for humans to parse as well as other computer languages. It creates a format that is easier to read than the default serializer.
+
+=head1 METHODS
+
+=over 4
+
+=item freeze($class, \\%hash)
+
+Receives two arguments. First is the class name, the second is the data to be serialized. Should return serialized string on success, undef on failure. Error message should be set using C&lt;set\_error()|CGI::Session::ErrorHandler/"set\_error()"&gt;
+
+=item thaw($class, $string)
+
+Received two arguments. First is the class name, second is the I data string. Should return thawed data structure on success, undef on failure. Error message should be set using C&lt;set\_error()|CGI::Session::ErrorHandler/"set\_error()"&gt;
+
+=back
+
+=head1 SEE ALSO
+
+L&lt;CGI::Session&gt;, L, L&lt;YAML::Syck&gt;.
diff --git a/TWiki/CGISessionTutorialDotPm.mdwn b/TWiki/CGISessionTutorialDotPm.mdwn
new file mode 100644 (file)
index 0000000..eca6e14
--- /dev/null
@@ -0,0 +1,329 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Tutorial - Extended CGI::Session manual
+
+=head1 STATE MAINTENANCE OVERVIEW
+
+Since HTTP is a stateless protocol, each subsequent click to a web site is treated as new request by the Web server. The server does not relate a visit with a previous one, thus all the state information from the previous requests are lost. This makes creating such applications as shopping carts, web sites requiring users to authenticate, impossible. So people had to do something about this despair situation HTTP was putting us in.
+
+For our rescue come such technologies as I and Is that help us save the users' session for a certain period. Since I and Is alone cannot take us too far (B), several other libraries have been developed to extend their capabilities and promise a more reliable solution. L&lt;CGI::Session|CGI::Session&gt; is one of them.
+
+Before we discuss this library, let's look at some alternative solutions.
+
+=head2 COOKIE
+
+Cookie is a piece of text-information that a web server is entitled to place in the user's hard disk, assuming a user agent (such as Internet Explorer, Mozilla, etc) is compatible with the specification. After the cookie is placed, user agents are required to send these cookies back to the server as part of the HTTP request. This way the server application ( CGI, for example ) will have a way of relating previous requests by the same user agent, thus overcoming statelessness of HTTP.
+
+Although I seem to be promising solution for the statelessness of HTTP, they do carry certain limitations, such as limited number of cookies per domain and per user agent and limited size on each cookie. User Agents are required to store at least 300 cookies at a time, 20 cookies per domain and allow 4096 bytes of storage for each cookie. They also rise several Privacy and Security concerns, the lists of which can be found on the sections B&lt;6-"Privacy"&gt; and B&lt;7-"Security Considerations"&gt; of B.
+
+=head2 QUERY STRING
+
+Query string is a string appended to URL following a question mark (?) such as:
+
+<http://my.dot.com/login.cgi?user=sherzodr;password=top-secret>
+
+As you probably guessed, it can also help you pass state information from a click to another, but how secure is it do you think, considering these URLs tend to get cached by most of the user agents and also logged in the servers access log, to which everyone can have access.
+
+=head2 HIDDEN FIELDS
+
+Hidden field is another alternative to using query strings and they come in two flavors: hidden fields used in POST methods and the ones in GET. The ones used in GET methods will turn into a true query strings once submitted, so all the disadvantages of QUERY\_STRINGs apply. Although POST requests do not have limitations of its sister-GET, the pages that hold them get cached by Web browser, and are available within the source code of the page (obviously). They also become unwieldily to manage when one has oodles of state information to keep track of ( for instance, a shopping cart or an advanced search engine).
+
+Query strings and hidden fields are also lost easily by closing the browser, or by clicking the browser's "Back" button.
+
+=head2 SERVER SIDE SESSION MANAGEMENT
+
+This technique is built upon the aforementioned technologies plus a server-side storage device, which saves the state data on the server side. Each session has a unique id associated with the data in the server. This id is also associated with the user agent either in the form of a I, a I, hidden field or any combination of the above. This is necessary to make the connection with the client and his data.
+
+Advantages:
+
+=over 4
+
+=item \*
+
+We no longer need to depend on User Agent constraints in cookie size.
+
+=item \*
+
+Sensitive data no longer need to be traveling across the network at each request (which is the case with query strings, cookies and hidden fields). The only thing that travels is the unique id generated for the session (B&lt;5767393932698093d0b75ef614376314&gt;, for instance), which should make no sense to third parties.
+
+=item \*
+
+User will not have sensitive data stored in his/her computer in unsecured file (which is a cookie file).
+
+=item \*
+
+It's possible to handle very big and even complex data structures transparently (which I do not handle).
+
+=back
+
+That's what CGI::Session is all about - implementing server side session management. Now is a good time to get feet wet.
+
+=head1 PROGRAMMING STYLE
+
+Server side session management system might be seeming awfully convoluted if you have never dealt with it. Fortunately, with L&lt;CGI::Session|CGI::Session&gt; all the complexity is handled by the library transparently. This section of the manual can be treated as an introductory tutorial to both logic behind session management, and to CGI::Session programming style.
+
+All applications making use of server side session management rely on the following pattern of operation regardless of the way the system is implemented:
+
+=over 4
+
+=item 1
+
+Check if the user has session cookie dropped in his computer from previous request
+
+=item 2
+
+If the cookie does not exist, create a new session identifier, and drop it as cookie to the user's computer.
+
+=item 3
+
+If session cookie exists, read the session ID from the cookie and load any previously saved session data from the server side storage. If session had any expiration date set it's useful to re-drop the same cookie to the user's computer so its expiration time will be reset to be relative to user's last activity time.
+
+=item 4
+
+Store any necessary data in the session that you want to make available for the next HTTP request.
+
+=back
+
+CGI::Session will handle all of the above steps. All you have to do is to choose what to store in the session.
+
+=head2 GETTING STARTED
+
+To make L&lt;CGI::Session|CGI::Session&gt;'s functionality available in your program do either of the following somewhere on top of your program file:
+
+use CGI::Session; # or require CGI::Session;
+
+Whenever you're ready to create a new session in your application, do the following:
+
+$session = new CGI::Session() or die CGI::Session-&gt;errstr;
+
+Above line will first try to re-initialize an existing session by consulting cookies and necessary QUERY\_STRING parameters. If it fails will create a brand new session with a unique ID, which is normally called I, I for short, and can be accessed through L&lt;id()|CGI::Session/id()&gt; - object method.
+
+We didn't check for any session cookies above, did we? No, we didn't, but CGI::Session did. It looked for a cookie called C, and if it found it tried to load existing session from server side storage (B in our case). If cookie didn't exist it looked for a QUERY\_STRING parameter called C. If all the attempts to recover session ID failed, it created a new session.
+
+NOTE: For the above syntax to work as intended your application needs to have write access to your computer's I folder, which is usually F in UNIX. If it doesn't, or if you wish to store this application's session files in a different place, you may pass the third argument like so:
+
+$session = new CGI::Session(undef, undef, \{Directory=&gt;'../tmp/sessions'\});
+
+Now it will store all the newly created sessions in (and will attempt to initialize requested sessions from) that folder. Don't worry if the directory hierarchy you want to use doesn't already exist. It will be created for you. For details on how session data are stored refer to L&lt;CGI::Session::Driver::file|CGI::Session::Driver::file&gt;, which is the default driver used in our above example.
+
+There is one small, but very important thing your application needs to perform after creating CGI::Session object as above. It needs to drop Session ID as an I into the user's computer. CGI::Session will use this cookie to identify the user at his/her next request and will be able to load his/her previously stored session data.
+
+To make sure CGI::Session will be able to read your cookie at next request you need to consult its C&lt;name()&gt; method for cookie's suggested name:
+
+$cookie = $query-&gt;cookie( -name =&gt; $session-&gt;name, -value =&gt; $session-&gt;id ); print $query-&gt;header( -cookie=&gt;$cookie );
+
+C&lt;name()&gt; returns C by default. If you prefer a different cookie name, you can change it as easily too, but you have to do it before CGI::Session object is created:
+
+CGI::Session-&gt;name("SID"); $session = new CGI::Session();
+
+Baking the cookie wasn't too difficult, was it? But there is an even easier way to send a cookie using CGI::Session:
+
+print $session-&gt;header();
+
+The above will create the cookie using L&lt;CGI::Cookie|CGI::Cookie&gt; and will return proper http headers using L&lt;CGI.pm|CGI&gt;'s L&lt;CGI|CGI/header()&gt; method. Any arguments to L&lt;CGI::Session|CGI::Session/header()&gt; will be passed to L&lt;CGI::header()|CGI/header()&gt;.
+
+Of course, this method of initialization will only work if client is accepting cookies. If not you would have to pass session ID in each URL of your application as QUERY\_STRING. For CGI::Session to detect it the name of the parameter should be the same as returned by L&lt;name()|CGI::Session/name()&gt;:
+
+printf ("[click me](\"$ENV{SCRIPT_NAME}?%s=%s\")", $session-&gt;name, $session-&gt;id);
+
+If you already have session id to be initialized you may pass it as the only argument, or the second argument of multi-argument syntax:
+
+$session = new CGI::Session( $sid ); $session = new CGI::Session( "serializer:freezethaw", $sid ); $session = new CGI::Session( "driver:mysql", $sid, \{Handle=&gt;$dbh\} );
+
+By default CGI::Session uses standard L&lt;CGI|CGI&gt; to parse queries and cookies. If you prefer to use a different, but compatible object you can pass that object in place of $sid:
+
+$cgi = new CGI::Simple(); $session = new CGI::Session ( $cgi ); $session = new CGI::Session( "driver:db\_file;serializer:storable", $cgi); # etc
+
+See L&lt;CGI::Simple|CGI::Simple&gt;
+
+=head2 STORING DATA
+
+L&lt;CGI::Session|CGI::Session&gt; offers L&lt;param() method|CGI::Session/param()&gt;, which behaves exactly as L&lt;CGI.pm's param()|CGI/param()&gt; with identical syntax. L&lt;param()|CGI::Session/param()&gt; is used for storing data in session as well as for accessing already stored data.
+
+Imagine your customer submitted a login form on your Web site. You, as a good host, wanted to remember the guest's name, so you can a) greet him accordingly when he visits your site again, or b) to be helpful by filling out I part of his login form, so the customer can jump right to the I field without having to type his username again.
+
+my $name = $cgi-&gt;param('username'); $session-&gt;param('username', $name);
+
+Notice, we're grabbing I value of the field using CGI.pm's (or another compatible library's) C&lt;param()&gt; method, and storing it in session using L&lt;CGI::Session|CGI::Session&gt;'s L&lt;param()|CGI::Session/param()&gt; method.
+
+If you have too many stuff to transfer into session, you may find yourself typing the above code over and over again. I've done it, and believe me, it gets very boring too soon, and is also error-prone. So we introduced the following handy method:
+
+$session-&gt;save\_param(['name']);
+
+If you wanted to store multiple form fields just include them all in the second list:
+
+$session-&gt;save\_param(['name', 'email']);
+
+If you want to store all the available I parameters you can omit the arguments:
+
+$session-&gt;save\_param();
+
+See L&lt;save\_param()|CGI::Session/save\_param&gt; for more details.
+
+When storing data in the session you're not limited to strings. You can store arrays, hashes and even most objects. You will need to pass them as references (except objects).
+
+For example, to get all the selected values of a scrolling list and store it in the session:
+
+my @fruits = $cgi-&gt;param('fruits'); $session-&gt;param('fruits', \\@fruits);
+
+For parameters with multiple values save\_param() will do the right thing too. So the above is the same as:
+
+$session-&gt;save\_param($cgi, ['fruits']);
+
+All the updates to the session data using above methods will not reflect in the data store until your application exits, or C&lt;$session&gt; goes out of scope. If, for some reason, you need to commit the changes to the data store before your application exits you need to call L&lt;flush()|CGI::Session/flush()&gt; method:
+
+$session-&gt;flush();
+
+I've written a lot of code, and never felt need for using C&lt;flush()&gt; method, since CGI::Session calls this method at the end of each request. There are, however, occasions I can think of one may need to call L&lt;flush()|CGI::Session/flush()&gt;.
+
+=head2 ACCESSING STORED DATA
+
+There's no point of storing data if you cannot access it. You can access stored session data by using the same L&lt;param() method|CGI::Session/param()&gt; you once used to store them. Remember the Username field from the previous section that we stored in the session? Let's read it back so we can partially fill the Login form for the user:
+
+$name = $session-&gt;param("name"); printf "
+
+<input name="\"name\"" type="\"text\"" value="\"%s\"" />
+
+", $name;
+
+To retrieve previously stored @fruits do not forget to de reference it:
+
+@fruits = @\{ $session-&gt;param('fruits') \};
+
+Very frequently, you may find yourself having to create pre-filled and pre-selected forms, like radio buttons, checkboxes and drop down menus according to the user's preferences or previous action. With text and textareas it's not a big deal - you can simply retrieve a single parameter from the session and hard code the value into the text field. But how would you do it when you have a group of radio buttons, checkboxes and scrolling lists? For this purpose, CGI::Session provides L&lt;load\_param()|CGI::Session/load\_param()&gt; method, which loads given session parameters to a CGI object (assuming they have been previously saved with L&lt;save\_param()|CGI::Session/save\_param()&gt; or alternative):
+
+$session-&gt;load\_param($cgi, ["fruits"]);
+
+Now when you say:
+
+print $cgi-&gt;checkbox\_group(fruits=&gt;['apple', 'banana', 'apricot']);
+
+See L&lt;load\_param()|CGI::Session/load\_param()&gt; for details.
+
+Generated checkboxes will be pre-filled using previously saved information. To see example of a real session-powered application consider <http://handalak.com/cgi-bin/subscriptions.cgi>
+
+If you're making use of L&lt;HTML::Template|HTML::Template&gt; to separate the code from the skin, you can as well associate L&lt;CGI::Session|CGI::Session&gt; object with HTML::Template and access all the parameters from within HTML files. We love this trick!
+
+$template = new HTML::Template(filename=&gt;"some.tmpl", associate=&gt;$session); print $template-&gt;output();
+
+Assuming the session object stored "first\_name" and "email" parameters while being associated with HTML::Template, you can access those values from within your "some.tmpl" file now:
+
+Hello [ ](mailto:<TMPL_VAR email>)!
+
+See L&lt;HTML::Template's online manual|HTML::Template&gt; for details.
+
+=head2 CLEARING SESSION DATA
+
+You store session data, you access session data and at some point you will want to clear certain session data, if not all. For this purpose L&lt;CGI::Session|CGI::Session&gt; provides L&lt;clear()|CGI::Session/clear()&gt; method which optionally takes one argument as an arrayref indicating which session parameters should be deleted from the session object:
+
+$session-&gt;clear(["~logged-in", "email"]);
+
+Above line deletes "~logged-in" and "email" session parameters from the session. And next time you say:
+
+$email = $session-&gt;param("email");
+
+it returns undef. If you omit the argument to L&lt;clear()|CGI::Session/clear()&gt;, be warned that all the session parameters you ever stored in the session object will get deleted. Note that it does not delete the session itself. Session stays open and accessible. It's just the parameters you stored in it gets deleted
+
+See L&lt;clear()|CGI::Session/clear()&gt; for details.
+
+=head2 DELETING A SESSION
+
+If there's a start there's an end. If session could be created, it should be possible to delete it from the disk for good:
+
+$session-&gt;delete();
+
+The above call to L&lt;delete()|CGI::Session/delete()&gt; deletes the session from the disk for good. Do not confuse it with L&lt;clear()|CGI::Session/clear()&gt;, which only clears certain session parameters but keeps the session open.
+
+See L&lt;delete()|CGI::Session/delete()&gt; for details.
+
+=head2 EXPIRATION
+
+L&lt;CGI::Session|CGI::Session&gt; provides limited means to expire sessions. Expiring a session is the same as deleting it via delete(), but deletion takes place automatically. To expire a session, you need to tell the library how long the session would be valid after the last access time. When that time is met, CGI::Session refuses to retrieve the session. It deletes the session and returns a brand new one. To assign expiration ticker for a session, use L&lt;expire()|CGI::Session/expire()&gt;:
+
+$session-&gt;expire(3600); # expire after 3600 seconds $session-&gt;expire('+1h'); # expire after 1 hour $session-&gt;expire('+15m'); # expire after 15 minutes $session-&gt;expire('+1M'); # expire after a month and so on.
+
+When session is set to expire at some time in the future, but session was not requested at or after that time has passed it will remain in the disk. When expired session is requested CGI::Session will remove the data from disk, and will initialize a brand new session.
+
+See L&lt;expire()|CGI::Session/expire()&gt; for details.
+
+Before CGI::Session 4.x there was no way of intercepting requests to expired sessions. CGI::Session 4.x introduced new kind of constructor, L&lt;load()|CGI::Session/load()&gt;, which is identical in use to L&lt;new()|CGI::Session/new()&gt;, but is not allowed to create sessions. It can only load them. If session is found to be expired, or session does not exist it will return an empty CGI::Session object. And if session is expired, in addition to being empty, its status will also be set to expired. You can check against these conditions using L&lt;empty()|CGI::Session/empty()&gt; and L&lt;is\_expired()|CGI::Session/is\_expired()&gt; methods. If session was loaded successfully object returned by C&lt;load()&gt; is as good a session as the one returned by C&lt;new()&gt;:
+
+$session = CGI::Session-&gt;load() or die CGI::Session-&gt;errstr; if ( $session-&gt;is\_expired ) \{ die "Your session expired. Please refresh your browser to re-start your session"; \} if ( $session-&gt;is\_empty ) \{ $session = $session-&gt;new(); \}
+
+Above example is worth an attention. Remember, all expired sessions are empty sessions, but not all empty sessions are expired sessions. Following this rule we have to check with C&lt;is\_expired()&gt; before checking with C&lt;is\_empty()&gt;. There is another thing about the above example. Notice how its creating new session when un existing session was requested? By calling C&lt;new()&gt; as an object method! Handy thing about that is, when you call C&lt;new()&gt; on a session object new object will be created using the same configuration as the previous object.
+
+For example:
+
+$session = CGI::Session-&gt;load("driver:mysql;serializer:storable", undef, \{Handle=&gt;$dbh\}); if ( $session-&gt;is\_expired ) \{ die "Your session is expired. Please refresh your browser to re-start your session"; \} if ( $session-&gt;is\_empty ) \{ $session = $session-&gt;new(); \}
+
+Initial C&lt;$session&gt; object was configured with B as the driver, B as the serializer and B&lt;$dbh&gt; as the database handle. Calling C&lt; new() &gt; on this object will return an object of the same configuration. So C&lt; $session &gt; object returned from C&lt; new() &gt; in the above example will use B as the driver, B as the serializer and B&lt;$dbh&gt; as the database handle.
+
+See L&lt;is\_expired()|CGI::Session/is\_expired()&gt;, L&lt;is\_empty()|CGI::Session/is\_empty()&gt;, L&lt;load()|CGI::Session/load()&gt; for details.
+
+Sometimes it makes perfect sense to expire a certain session parameter, instead of the whole session. I usually do this in my login enabled sites, where after the user logs in successfully, I set his/her "\_logged\_in" session parameter to true, and assign an expiration ticker on that flag to something like 30 minutes. It means, after 30 idle minutes CGI::Session will L&lt;clear|CGI::Session/clear()&gt; "\_logged\_in" flag, indicating the user should log in over again. I agree, the same effect can be achieved by simply expiring() the session itself, but by doing this we would loose other session parameters, such as user's shopping cart, session-preferences and the like.
+
+This feature can also be used to simulate layered authentication, such as, you can keep the user's access to his/her personal profile information for as long as 60 minutes after a successful login, but expire his/her access to his credit card information after 5 idle minutes. To achieve this effect, we will use L&lt;expire()|CGI::Session/expire()&gt; method again:
+
+$session-&gt;expire(\_profile\_access, '1h'); $session-&gt;expire(\_cc\_access, '5m');
+
+With the above syntax, the person will still have access to his personal information even after 5 idle hours. But when he tries to access or update his/her credit card information, he may be displayed a "login again, please" screen.
+
+See L&lt;expire()|CGI::Session/expire()&gt; for details.
+
+This concludes our discussion of CGI::Session programming style. The rest of the manual covers some L&lt;"SECURITY"&gt; issues. Driver specs from the previous manual were moved to L&lt;CGI::Session::Driver|CGI::Session::Driver&gt;.
+
+=head1 SECURITY
+
+"How secure is using CGI::Session?", "Can others hack down people's sessions using another browser if they can get the session id of the user?", "Are the session ids easy to guess?" are the questions I find myself answering over and over again.
+
+=head2 STORAGE
+
+Security of the library does in many aspects depend on the implementation. After making use of this library, you no longer have to send all the information to the user's cookie except for the session id. But, you still have to store the data in the server side. So another set of questions arise, can an evil person get access to session data in your server, even if he does, can he make sense out of the data in the session file, and even if he can, can he reuse the information against a person who created that session. As you see, the answer depends on yourself who is implementing it.
+
+=over 4
+
+=item \*
+
+First rule of thumb, do not store users' passwords or other sensitive data in the session, please. If you have to, use one-way encryption, such as md5, or SHA-1-1. For my own experience I can assure you that in properly implemented session-powered Web applications there is never a need for it.
+
+=item \*
+
+Default configuration of the driver makes use of L&lt;Data::Dumper|Data::Dumper&gt; class to serialize data to make it possible to save it in the disk. Data::Dumper's result is a human readable data structure, which, if opened, can be interpreted easily. If you configure your session object to use either L&lt;Storable|CGI::Session::Serialize::storable&gt; or L&lt;FreezeThaw|CGI::Session::Serialize::freezethaw&gt; as a serializer, this would make it more difficult for bad guys to make sense out of session data. But don't use this as the only precaution. Since evil fingers can type a quick program using L&lt;Storable|Storable&gt; or L&lt;FreezeThaw|FreezeThaw&gt; to decipher session files very easily.
+
+=item \*
+
+Do not allow anyone to update contents of session files. If you're using L serialized data string needs to be eval()ed to bring the original data structure back to life. Of course, we use L&lt;Safe|Safe&gt; to do it safely, but your cautiousness does no harm either.
+
+=item \*
+
+Do not keep sessions open for very long. This will increase the possibility that some bad guy may have someone's valid session id at a given time (acquired somehow). To do this use L&lt;expire()|CGI::Session/expire()&gt; method to set expiration ticker. The more sensitive the information on your Web site is, the sooner the session should be set to expire.
+
+=back
+
+=head2 SESSION IDs
+
+Session ids are not easily guessed (unless you're using L)! Default configuration of CGI::Session uses L&lt;Digest::MD5|CGI::Session::ID::md5&gt; to generate random, 32 character long identifier. Although this string cannot be guessed as easily by others, if they find it out somehow, can they use this identifier against the other person?
+
+Consider the scenario, where you just give someone either via email or an instant messaging a link to a Web site where you're currently logged in. The URL you give to that person contains a session id as part of a query string. If the site was initializing the session solely using query string parameter, after clicking on that link that person now appears to that site as you, and might have access to all of your private data instantly.
+
+Even if you're solely using cookies as the session id transporters, it's not that difficult to plant a cookie in the cookie file with the same id and trick the web browser to send that particular session id to the server. So key for security is to check if the person who's asking us to retrieve a session data is indeed the person who initially created the session data.
+
+One way to help with this is by also checking that the IP address that the session is being used from is always same. However, this turns out not to be practical in common cases because some large ISPs (such as AOL) use proxies which cause each and every request from the same user to come from different IP address.
+
+If you have an application where you are sure your users' IPs are constant during a session, you can consider enabling an option to make this check:
+
+use CGI::Session ( '-ip\_match' );
+
+For backwards compatibility, you can also achieve this by setting $CGI::Session::IP\_MATCH to a true value. This makes sure that before initializing a previously stored session, it checks if the ip address stored in the session matches the ip address of the user asking for that session. In which case the library returns the session, otherwise it dies with a proper error message.
+
+=head1 LICENSING
+
+For support and licensing see L&lt;CGI::Session|CGI::Session&gt;
index 2d38664..9de9b23 100644 (file)
@@ -10,45 +10,39 @@ If your user topic is not protected from changes by other people, and you don't
 
 If your old e-mail addresses are all invalid (you can't receive mail there any more) and you have forgotten your password, please contact 0 for help.
 
-<form action="http://www.dementia.org/twiki/passwd/%WEB%/%TOPIC%" method="post" name="passwd">
+<form action="http://www.dementia.org/twiki/manage/%WEB%/%TOPIC%" method="post" name="manage">
   <div>
-    <div><strong>After submitting this form your e-mail will be changed, and you will be returned to this form.</strong></div>
+    <div><strong>Sorry, the password system is currently read only, please contact 0</strong></div>
     <div> Registered e-mail addresses for currently logged in user (<code>admin</code>): </div>
     <div>
-      <table border="0" cellpadding="0" cellspacing="0" style="border-width: 0px">
+      <table border="0" cellpadding="0" cellspacing="0" rules="none" style="border-width: 0px">
         <tr>
-          <td style="border-width: 0px">   </td>
-          <td style="border-width: 0px"> Fields marked <code><font color="red">**</font></code> are required </td>
+          <td bgcolor="transparent" style="">   </td>
+          <td bgcolor="transparent" style=""> Fields marked <code><font color="red">**</font></code> are required </td>
         </tr>
         <tr>
-          <td align="right" style="border-width: 0px"> Your [[TWiki/LoginName]]: </td>
-          <td style="border-width: 0px"><input name="username" size="40" type="text" value="admin" /> <code><font color="red">**</font></code></td>
+          <td align="right" bgcolor="transparent" style=""> Your [[TWiki/LoginName]]: </td>
+          <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="username" size="40" type="text" value="admin" /> <code><font color="red">**</font></code></td>
         </tr>
         <tr>
-          <td align="right" style="border-width: 0px"> Password: </td>
-          <td style="border-width: 0px"><input name="oldpassword" size="40" type="password" value="" /> <code><font color="red">**</font></code></td>
+          <td align="right" bgcolor="transparent" style=""> Password: </td>
+          <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="oldpassword" size="40" type="password" value="" /> <code><font color="red">**</font></code></td>
         </tr>
         <tr>
-          <td align="right" style="border-width: 0px"> New e-mails (space-separated list): </td>
-          <td style="border-width: 0px"><input name="email" size="40" type="text" /> <code><font color="red">**</font></code></td>
+          <td align="right" bgcolor="transparent" style=""> New e-mails (space-separated list): </td>
+          <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="email" size="40" type="text" /> <code><font color="red">**</font></code></td>
         </tr>
       </table>
     </div>
-    <div><input name="TopicName" type="hidden" value="%TOPIC%" /> <input name="action" type="hidden" value="changePassword" /> <input type="submit" value="Change e-mail address" /></div>
+    <div><input name="TopicName" type="hidden" value="%TOPIC%" /> <input name="action" type="hidden" value="changePassword" /> <input %notmodifyable%="%NOTMODIFYABLE%" type="submit" value="Change e-mail address" /></div>
   </div>
 </form>
 
 <div>
   <ul>
-    <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> If you have any questions, please contact 0. </li>
-    <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> [[Main/TWikiUsers]] has a list of other TWiki users. </li>
+    <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> If you have any questions, please contact 0 </li>
+    <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> [[Main/TWikiUsers]] has a list of other TWiki users </li>
   </ul>
 </div>
 
 **_Related topics:_** [[ChangePassword]], [[ResetPassword]], [[UserToolsCategory]], [[AdminToolsCategory]]
-
-<table bgcolor="yellow">
-  <tr>
-    <td><strong><em>Note to administrator:</em></strong> This form applies only if TWiki uses a {PasswordManager} that supports storing e-mails (e.g. TWiki::Users::HtPasswdUser). Otherwise replace this topic with a note describing how to change registered e-mail in your organization). </td>
-  </tr>
-</table>
index e160179..efcdfd2 100644 (file)
@@ -2,47 +2,41 @@
 
 **_Forgotten your password?_** Use [[ResetPassword]] instead.
 
-<form action="http://www.dementia.org/twiki/passwd/TWiki/WebHome" method="post" name="passwd">
+<form action="http://www.dementia.org/twiki/manage/TWiki/WebHome" method="post" name="manage">
   <div>
-    <div><strong>After submitting this form your password will be changed.</strong></div>
+    <div><strong>Sorry, the password system is currently read only, please contact 0</strong></div>
     <div>
-      <table border="0" cellpadding="0" cellspacing="0" style="border-width: 0px">
+      <table border="0" cellpadding="0" cellspacing="0" rules="none" style="border-width: 0px">
         <tr>
-          <td colspan="2" style="border-width: 0px"> Fields marked <code><font color="red">**</font></code> are required </td>
+          <td bgcolor="transparent" colspan="2" style=""> Fields marked <code><font color="red">**</font></code> are required </td>
         </tr>
         <tr>
-          <td align="right" style="border-width: 0px"> Your [[TWiki/LoginName]]: </td>
-          <td style="border-width: 0px"><input name="username" size="40" type="text" value="admin" /> <code><font color="red">**</font></code></td>
+          <td align="right" bgcolor="transparent" style=""> Your [[TWiki/LoginName]]: </td>
+          <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="username" size="40" type="text" value="admin" /> <code><font color="red">**</font></code></td>
         </tr>
         <tr>
-          <td align="right" style="border-width: 0px"> Current password: </td>
-          <td style="border-width: 0px"><input name="oldpassword" size="40" type="password" value="" /> <code><font color="red">**</font></code></td>
+          <td align="right" bgcolor="transparent" style=""> Current password: </td>
+          <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="oldpassword" size="40" type="password" value="" /> <code><font color="red">**</font></code></td>
         </tr>
         <tr>
-          <td align="right" style="border-width: 0px"> New password: </td>
-          <td style="border-width: 0px"><input name="password" size="40" type="password" /> <code><font color="red">**</font></code></td>
+          <td align="right" bgcolor="transparent" style=""> New password: </td>
+          <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="password" size="40" type="password" /> <code><font color="red">**</font></code></td>
         </tr>
         <tr>
-          <td align="right" style="border-width: 0px"> Retype new password: </td>
-          <td style="border-width: 0px"><input name="passwordA" size="40" type="password" /> <code><font color="red">**</font></code></td>
+          <td align="right" bgcolor="transparent" style=""> Retype new password: </td>
+          <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="passwordA" size="40" type="password" /> <code><font color="red">**</font></code></td>
         </tr>
       </table>
     </div>
-    <div><input name="TopicName" type="hidden" value="%TOPIC%" /> <input name="action" type="hidden" value="changePassword" /> <input type="submit" value="Change password" /></div>
+    <div><input name="TopicName" type="hidden" value="%TOPIC%" /> <input name="action" type="hidden" value="changePassword" /> <input %notmodifyable%="%NOTMODIFYABLE%" type="submit" value="Change password" /></div>
   </div>
 </form>
 
 <div>
   <ul>
-    <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> If you have any questions, please contact 0. </li>
-    <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> [[Main/TWikiUsers]] has a list of other TWiki users. </li>
+    <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> If you have any questions, please contact 0 </li>
+    <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> [[Main/TWikiUsers]] has a list of other TWiki users </li>
   </ul>
 </div>
 
 **_Related topics:_** [[ResetPassword]], [[ChangeEmailAddress]], [[UserToolsCategory]], [[AdminToolsCategory]]
-
-<table bgcolor="yellow">
-  <tr>
-    <td><strong><em>Note to administrator:</em></strong> This form applies only if TWiki uses a {PasswordManager} that supports changing passwords. Otherwise replace this topic with a note describing how to change the password in your organization. See [[Main/TWikiUserAuthentication]] for more information. </td>
-  </tr>
-</table>
index b15a4c5..8ddb37a 100644 (file)
@@ -1,23 +1,21 @@
 # <a name="Classic Skin"></a> Classic Skin
 
-The classic TWiki skin is the traditional TWiki skin, as seen in previous TWiki versions.
+The classic TWiki skin is a bare bone and functional skin, supporting any browser, and has a minimum of graphics
+
+This is not really a skin. It is the set of default templates, shown if no skin is activated. The default templates are part of every TWiki distribution.
 
 ## <a name="Skin Info"></a> Skin Info
 
 <table border="1" cellpadding="0" cellspacing="0">
   <tr>
     <td align="right"> Description: </td>
-    <td> Bare bone and functional, for any browser, with a minimum of graphics </td>
+    <td> The classic TWiki skin, bare bone and functional, for any browser, with a minimum of graphics </td>
   </tr>
   <tr>
     <td align="right"> Screenshot: </td>
     <td><a href="http://www.dementia.org/twiki//view/fullscreen.gif"><img alt="Click for full screen image" height="130" src="http://www.dementia.org/twiki//view/screenshot.gif" width="600" /></a></td>
   </tr>
   <tr>
-    <td align="right"> Preview: </td>
-    <td>[[%WEB%/%TOPIC%?skin=classic]]</td>
-  </tr>
-  <tr>
     <td align="right"> Base Name: </td>
     <td> classic </td>
   </tr>
@@ -27,13 +25,17 @@ The classic TWiki skin is the traditional TWiki skin, as seen in previous TWiki
   </tr>
   <tr>
     <td align="right"> Skin Version: </td>
-    <td> 25 Jul 2004 (v1.000) </td>
+    <td> 21 May 2007 (v1.001) </td>
   </tr>
   <tr>
     <td align="right"> Change History: </td>
     <td>  </td>
   </tr>
   <tr>
+    <td align="right"> 21 May 2007 </td>
+    <td> Bugs:Item3969 - 8bit email fix (TWiki:Main.WillNorris) </td>
+  </tr>
+  <tr>
     <td align="right"> 25 Jul 2004: </td>
     <td> Initial version (v1.000) </td>
   </tr>
@@ -49,12 +51,10 @@ The classic TWiki skin is the traditional TWiki skin, as seen in previous TWiki
     <td align="right"> Feedback: </td>
     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
   </tr>
-  <tr>
-    <td align="right"> Appraisal: </td>
-    <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
-  </tr>
 </table>
 
 **_Note:_** The Description, Screenshot and Base Name rows are needed by the [[TWikiSkinBrowser]]
 
-**_Related topic:_** [[TWikiSkins]], [[TWikiSkinBrowser]], [[UserDocumentationCategory]], [[AdminDocumentationCategory]]
+**_Related topic:_** [[TWikiSkins]], [[TWikiSkinBrowser]]
+
+-- TWiki:Main/PeterThoeny - 25 Jul 2004
index e8ad279..ae989f1 100644 (file)
@@ -2,12 +2,9 @@
 
 **Comment Plugin lets users quickly post comments to a page without an edit/preview/save cycle.**
 
-<div style="background-color: #ffc">WARNING: TWiki-4 only. If you want to use this plugin with an earlier version of TWiki, please use <a href="http://twiki.org/cgi-bin/attach/Plugins/CommentPlugin?filename=CommentPlugin.zip&revInfo=1" target="_top">revision 31 of the zip</a>.</div>
-
-<div>
-  <ul>
+<div><span>On this page:</span><ul>
     <li><a href="#Features"> Features</a></li>
-    <li><a href="#Syntax Rules"> Syntax Rules</a><ul>
+    <li><a href="#Syntax"> Syntax</a><ul>
         <li><a href="#Positioning the comment"> Positioning the comment</a><ul>
             <li><a href="#Location relative to %COMMENT ta"> Location relative to <code>%COMMENT</code> tag</a></li>
             <li><a href="#Location relative to a TWiki anc"> Location relative to a TWiki anchor</a></li>
@@ -23,6 +20,7 @@
         <li><a href="#The <code>PROMPT</code> template"> The PROMPT template</a><ul>
             <li><a href="#Providing attribute values"> Providing attribute values</a></li>
             <li><a href="#Special variables"> Special variables</a></li>
+            <li><a href="#Customisation example with custo"> Customisation example with custom form template</a></li>
           </ul>
         </li>
         <li><a href="#The <code>OUTPUT</code> template"> The OUTPUT template</a></li>
   </ul>
 </div>
 
+Related topics: [[CommentPluginTemplates]], [[CommentPluginExamples]]
+
+<div style="background-color: #ffc">WARNING: TWiki-4 only. If you want to use this plugin with an earlier version of TWiki, please use <a href="http://twiki.org/cgi-bin/attach/Plugins/CommentPlugin?filename=CommentPlugin.zip&revInfo=1" target="_top">revision 31 of the zip</a>.</div>
+
 ## <a name="Features"></a> Features
 
 Inserts an edit box into the page that allows users to type in and save comments. Comments can be made
@@ -43,58 +45,11 @@ Inserts an edit box into the page that allows users to type in and save comments
 - signed or unsigned, dated or undated (as defined by a template),
 - in other topics, or other positions within the current topic.
 
-## <a name="Syntax Rules"></a> Syntax Rules
-
-Write the command `%COMMENT{` _attributes_ `}%` anywhere in a TWiki topic. `%COMMENT%` is also legal.
+## <a name="Syntax"></a> Syntax
 
-<a name="StandardAttrs"></a> The following attributes are recognized (see also [[additional attributes|Main/WebHome#MoreAttrs]]):
+<a name="StandardAttrs"></a> Write <code>%COMMENT\{_attributes_\}%</code> anywhere in a TWiki topic.
 
-<table border="1" cellpadding="0" cellspacing="0">
-  <tr>
-    <th bgcolor="#99CCCC"><strong> Name </strong></th>
-    <th bgcolor="#99CCCC"><strong> Description </strong></th>
-  </tr>
-  <tr>
-    <td><code>type</code></td>
-    <td> This is the name of the template to use for this comment. Comment templates are defined in a TWiki template - see [[Main/WebHome#TemPlates]], below. If this attribute is not defined, the type is whatever is defined by COMMENTPLUGIN_DEFAULT_TYPE, either in this topic or in your [[Main/WebPreferences]]. By default this is 'below'. </td>
-  </tr>
-  <tr>
-    <td><code>default</code></td>
-    <td> Default text to put into the textarea of the prompt. </td>
-  </tr>
-  <tr>
-    <td><code>target</code></td>
-    <td> Name of the topic to add the comment to. Defaults to the current topic. </td>
-  </tr>
-  <tr>
-    <td><code>location</code></td>
-    <td> Regular expression specifying the comment location in the target topic. Read <em>carefully</em> below! </td>
-  </tr>
-  <tr>
-    <td><code>mode</code></td>
-    <td> For compatability with older versions only, synonymous with <code>type</code></td>
-  </tr>
-  <tr>
-    <td><code>nonotify</code></td>
-    <td> Set to "on" to disable change notification for target topics </td>
-  </tr>
-  <tr>
-    <td><code>noform</code></td>
-    <td> Set to "on" to disable the automatic form that encloses your comment block - <em>remember</em> to insert <code>&lt;form&gt;</code> tags yourself! See [[Main/CommentPluginExamples#noform]] for an example. </td>
-  </tr>
-  <tr>
-    <td><code>nopost</code></td>
-    <td> Set to "on" to disable insertion of the posted text into the topic. </td>
-  </tr>
-  <tr>
-    <td><code>remove</code></td>
-    <td> Set to "on" to remove the comment prompt after the first time it is clicked. </td>
-  </tr>
-  <tr>
-    <td><code>button</code></td>
-    <td> Button label text; by default <code>Add comment</code>. </td>
-  </tr>
-</table>
+(See also [[additional attributes|Main/WebHome#MoreAttrs]])
 
 ### <a name="Positioning the comment"></a> Positioning the comment
 
@@ -124,7 +79,7 @@ Getting more sophisticated, you can also specify a regular expression for the ta
 
 will place comments above the first occurence of the string `Flights of Fancy` in the current topic.
 
-**Warning** of course, if a user's comment contains the string "Flights of Fancy" they may and up _changing the location_ for the next comment! Also, if you use a tag in the location, then you've just inserted another tag in the page that contains the `%COMMENT`! So be very careful how you specify the RE for `location`. Note that the RE is matched using perl "multiple line" mode, so ^ and $ match the start of a line and the end of a line respectively.
+**Warning** of course, if a user's comment contains the string "Flights of Fancy" they may and up _changing the location_ for the next comment! Also, if you use a tag in the location, then you've just inserted another tag in the page that contains the `%COMMENT`! So be very careful how you specify the RE for `location`. Note that the RE is matched using perl "multiple line" mode, so ^ and $ match the start of a line and the end of a line respectively. %BR% Also note that you cannot have the text `location="` just before the location.
 
 I look forward to someone leveraging this feature to create - for example - threaded conversations using `%COMMENT`.
 
@@ -134,7 +89,7 @@ If you specify an anchor _and_ a `location`, the anchor will be ignored.
 
 Templates are used to define the "comment style" i.e. how comments appear in the page. The default is to add comments in "Blog like" style using bulleted lists, with the most recent comment at the top, but many other styles are available such as tables or Wiki thread mode comments. It is easy to define your own customer styles as well.
 
-A set of default comment templates are shipped with the plugin. These are:
+A set of default comment templates are shipped with the plugin - see also [[CommentPluginTemplates]]:
 
 <table border="1" cellpadding="0" cellspacing="0">
   <tr>
@@ -158,6 +113,10 @@ A set of default comment templates are shipped with the plugin. These are:
     <td> Comments, signed and dated (server time), added immediately below the target anchor, or the <code>%COMMENT</code> if no anchor is specified </td>
   </tr>
   <tr>
+    <td><code>belowthreadmode</code></td>
+    <td> Comments, signed and dated, added recurse after comment box </td>
+  </tr>
+  <tr>
     <td><code>threadmode</code></td>
     <td> Wiki thread mode comment, signed and dated (server time) </td>
   </tr>
@@ -169,6 +128,26 @@ A set of default comment templates are shipped with the plugin. These are:
     <td><code>tableappend</code></td>
     <td> Comments, signed and dated (server time), formatted as an HTML table row, added above the anchor (which must be in an HTML &lt;table&gt;) </td>
   </tr>
+  <tr>
+    <td><code>action</code></td>
+    <td> Action added to action table directly above comment box (requires TWiki:Plugins/ActionTrackerPlugin) </td>
+  </tr>
+  <tr>
+    <td><code>table</code></td>
+    <td> Tablerows adding on end </td>
+  </tr>
+  <tr>
+    <td><code>toctalk</code></td>
+    <td> Talk using TOC adding on end </td>
+  </tr>
+  <tr>
+    <td><code>bookmark</code></td>
+    <td> Create a list of annotated bookmarks </td>
+  </tr>
+  <tr>
+    <td><code>return</code></td>
+    <td> Post to a different topic and return </td>
+  </tr>
 </table>
 
 Your local installation may add more template types as well - see [[Customisation|Main/WebHome#TemPlates]], below.
@@ -197,9 +176,13 @@ This allows for several levels of customisation:
 3. To override templates on a **web-by-web basis**, add a topic `UserCommentsTemplate` to the web (this will replace TWiki.UserCommentsTemplate)
 4. To override templates **for a specific skin**, add them to TWiki.UserComments&lt;Skin&gt;Template (where &lt;Skin&gt; is the name of the skin with the first letter capitalised, e.g. Pattern)
 
-%X% Templates are picked up by following the [[standard TWiki rules|Main/TWikiTemplates#Finding_Templates]] for locating template files. Note that you can use `%TMPL:INCLUDE` to include other files of templates.
+You can also define a **comment template in a topic**, by passing the topic location with `templatetopic`. For example:
+
+> %COMMENT{type="blogpost" templatetopic="BlogPostCommentTemplate" target="%TOPIC%" button="Add comment" }%
+>
+> `templatetopic` accepts `topic` or `web.topic` syntax. See an example in [[CommentPluginExamples:templatetopic|Main/CommentPluginExamples#TemplateTopic]].
 
-%X% Note that from TWiki release 4.1.0 leading and trailing whitespace is no longer stripped. This means that when you upgrade to TWiki 4.1.X you may need to remove the first line break in your custom comment templates. See [[TWikiReleaseNotes04x01]] for more information.
+%X% Templates are picked up by following the [[standard TWiki rules|Main/TWikiTemplates#Finding_Templates]] for locating template files. Note that you can use `%TMPL:INCLUDE` to include other files of templates. %BR% %X% Note that from TWiki release 4.1.0 leading and trailing whitespace is no longer stripped. This means that when you upgrade to TWiki 4.1.X you may need to remove the first line break in your custom comment templates. See [[TWikiReleaseNotes04x01]] for more information.
 
 ### <a name="Customisation example"></a> Customisation example
 
@@ -293,6 +276,10 @@ As well as support for all the usual TWiki variables in templates, the following
     <td><code>comment_nopost</code></td>
     <td> As passed to %COMMENT </td>
   </tr>
+  <tr>
+    <td><code>comment_templatetopic</code></td>
+    <td> As passed to %COMMENT </td>
+  </tr>
 </table>
 
 Note that `comment_location` overrides `comment_anchor`, and both override `comment_index`. Example, shows an "I Approve" button that adds your approval signature to the end of the topic:
@@ -304,6 +291,27 @@ Note that `comment_location` overrides `comment_anchor`, and both override `comm
     <input type="hidden" name="comment" value="I Approve" />
     </form>
 
+#### <a name="Customisation example with custo"></a> Customisation example with custom form template
+
+Write a custom form in a topic.
+
+- In the form set the location of the prompt with `%COMMENTPROMPT%`; the prompt will be positioned here.
+- In %COMMENT use parameter `noform="on"`
+- In %COMMENT use parameter `templatetopic` to point to the topic with the form template
+
+Example form:
+
+    %TMPL:DEF{FORM:example}%
+    <form method="post" action="%SCRIPTURL{save}%/%BASEWEB%/%BASETOPIC%" enctype="application/x-www-form-urlencoded" name="examplecomment" id="examplecomment">
+    <input type="hidden" name="redirectto" value="%BASEWEB%.%BASETOPIC%" />
+    %COMMENTPROMPT%
+    </form>
+    %TMPL:END%
+
+Example comment:
+
+    %COMMENT{noform="on" type="example" templatetopic="Sandbox.CommentPluginTemplateExample" target="%TOPIC%" button="Add comment" }%
+
 ### <a name="The &lt;code&gt;OUTPUT&lt;/code&gt; template"></a> The `OUTPUT` template
 
 The `OUTPUT` template defines the format for the text that actually gets embedded into the topic. All the usual TWiki variables are available in the `PROMPT` definition, but note that they get expanded _when the comment is inserted in the text_, so time, date and username will refer to the time and date when the comment was made, and the user who made it.
@@ -331,6 +339,13 @@ There are also four position tags that are used to indicate where the comment sh
 
 Note that these position tags are obviously mutually exclusive. If you define more than one, the result is undefined. If none is present, the default is taken from the plugin setting `DEFAULT_TYPE`
 
+<table border="1" cellpadding="0" cellspacing="0">
+  <tr>
+    <td><code>%COMMENTPROMPT%</code></td>
+    <td> Use with a custom form. If present, the comment prompt will be positioned here. </td>
+  </tr>
+</table>
+
 All the usual [[TWikiVariables]] that can be used in a topic template can also be used in an `OUTPUT` template. See [[TWikiVariables]] for details.
 
 ## <a name="Settings"></a> Settings
@@ -370,62 +385,76 @@ These can be set in TWikiPreferences, in WebPreferences or in individual topics.
 
 ## <a name="Plugin Info"></a> Plugin Info
 
+Another great TWiki extension from the [![](http://www.dementia.org/twiki//view/wikiringlogo20x20.png) **WikiRing** ](http://wikiring.com) - working together to improve your wiki experience!
+
 <table border="1" cellpadding="0" cellspacing="0">
   <tr>
     <td align="right"> Plugin Author: </td>
-    <td> TWiki:Main.DavidWeller, TWiki:Main.PeterMasiar, TWiki:Main.CrawfordCurrie <a href="http://www.c-dot.co.uk" target="_top">http://www.c-dot.co.uk</a></td>
+    <td> TWiki:Main.CrawfordCurrie <a href="http://www.c-dot.co.uk" target="_top">http://www.c-dot.co.uk</a> inspired by the work of TWiki:Main.DavidWeller and TWiki:Main.PeterMasiar </td>
   </tr>
   <tr>
-    <td align="right"> Copyright: </td>
-    <td> © 2004, TWiki:Main.CrawfordCurrie<br />© 2004-2007 TWiki:TWiki.TWikiContributor </td>
+    <td align="right"> Plugin Version: </td>
+    <td> 15776 (22 Jan 2008) </td>
   </tr>
   <tr>
-    <td align="right"> License: </td>
-    <td> GPL (<a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GNU General Public License</a>) </td>
+    <td align="right"> Change History: </td>
+    <td>   </td>
   </tr>
   <tr>
-    <td align="right"> Plugin Version: </td>
-    <td> 12750 (04 Feb 2007) </td>
+    <td align="right"> 5 Sep 2007 </td>
+    <td> TWikibug:Item3689 corrected <code>location</code> handling TWikibug:Item4181 added [[Main/VarCOMMENT]] TWikibug:Item4402 corrected access check </td>
   </tr>
   <tr>
-    <td align="right"> Change History: </td>
-    <td>  </td>
+    <td align="right"> 22 Jun 2007 </td>
+    <td> Removed the long-deprecated <code>%TIME</code> (use %GMTIME instead). Minor doc changes </td>
+  </tr>
+  <tr>
+    <td align="right"> 14021 </td>
+    <td> TWikibug:Item3755 Fixed incorrect handling of line terminators when targeting an anchor </td>
+  </tr>
+  <tr>
+    <td align="right"> 13311 </td>
+    <td> Added option to define a comment template in any topic. Pass the topic location with <code>templatetopic</code> (either <code>topic</code> or <code>web.topic</code>). See an example in [[Main/CommentPluginExamples#TemplateTopic]]. </td>
+  </tr>
+  <tr>
+    <td align="right"> 12822 </td>
+    <td> TWikibug:Item3598 minor doc fixes </td>
   </tr>
   <tr>
     <td align="right"> 12750 </td>
-    <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item3510" rel="nofollow">Item3510</a> added a note about the changed template spec in TWiki 4.1.0. Code remains unchanged </td>
+    <td> TWikibug:Item3510 added a note about the changed template spec in TWiki 4.1.0. Code remains unchanged </td>
   </tr>
   <tr>
     <td align="right"> 11358 </td>
-    <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item2802" rel="nofollow">Item2802</a> moved SHORTDESCRIPTION to .pm. Coded up TWiki:main.PankajPant's suggestions as <code>nopost</code> and <code>remove</code>. Added default text for the %COMMENT as requested by TWiki:Main.AndyGlew </td>
+    <td> TWikibug:Item2802 moved SHORTDESCRIPTION to .pm. Coded up TWiki:main.PankajPant's suggestions as <code>nopost</code> and <code>remove</code>. Added default text for the %COMMENT as requested by TWiki:Main.AndyGlew </td>
   </tr>
   <tr>
     <td align="right"> 11118 </td>
-    <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item2322" rel="nofollow">Item2322</a> removed span tag around oneliner bullet output </td>
+    <td> TWikibug:Item2322 removed span tag around oneliner bullet output </td>
   </tr>
   <tr>
     <td align="right"> 8788 </td>
-    <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1465" rel="nofollow">Item1465</a> Item1577: reverted 8433 to fix inclusion of correct user templates </td>
+    <td> TWikibug:Item1465 Item1577: reverted 8433 to fix inclusion of correct user templates </td>
   </tr>
   <tr>
     <td align="right"> 8787 </td>
-    <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1573" rel="nofollow">Item1573</a> renamed standard templates topic to avoid naming clash on Windows, where filenames are case-insensitive </td>
+    <td> TWikibug:Item1573 renamed standard templates topic to avoid naming clash on Windows, where filenames are case-insensitive </td>
   </tr>
   <tr>
     <td align="right"> 8433 </td>
-    <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1465" rel="nofollow">Item1465</a> Fix 'TWiki.' to 'TWiki.'; also fixed include 'UserComments' to 'UserCommentsTemplate' (at least that is what the doc suggests) </td>
+    <td> TWikibug:Item1465 Fix 'TWiki.' to 'TWiki.'; also fixed include 'UserComments' to 'UserCommentsTemplate' (at least that is what the doc suggests) </td>
   </tr>
   <tr>
     <td align="right"> 7427 </td>
-    <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item845" rel="nofollow">Item845</a> removed duplicate date in default comments; stick with server time </td>
+    <td> TWikibug:Item845 removed duplicate date in default comments; stick with server time </td>
   </tr>
   <tr>
     <td align="right"> 7251 </td>
-    <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item810" rel="nofollow">Item810</a> fix for user template inclusion; reorganised templates to make customisation easier </td>
+    <td> TWikibug:Item810 fix for user template inclusion; reorganised templates to make customisation easier </td>
   </tr>
   <tr>
     <td align="right"> 5906 </td>
-    <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item143" rel="nofollow">Item143</a> apache warning from comment plugin when CommentsTmpl.txt not found </td>
+    <td> TWikibug:Item143 apache warning from comment plugin when CommentsTmpl.txt not found </td>
   </tr>
   <tr>
     <td align="right"> 5519 </td>
@@ -472,8 +501,12 @@ These can be set in TWikiPreferences, in WebPreferences or in individual topics.
     <td> 06 Mar 2002 initial commit </td>
   </tr>
   <tr>
-    <td align="right"> Perl Version: </td>
-    <td> &gt;= 5.6.1 </td>
+    <td align="right"> Copyright: </td>
+    <td> © 2004, TWiki:Main.CrawfordCurrie<br />© 2004-2007 TWiki:TWiki.TWikiContributor </td>
+  </tr>
+  <tr>
+    <td align="right"> License: </td>
+    <td> GPL (<a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GNU General Public License</a>) </td>
   </tr>
   <tr>
     <td align="right"> Plugin Home: </td>
@@ -486,5 +519,3 @@ These can be set in TWikiPreferences, in WebPreferences or in individual topics.
 </table>
 
 **_Related Topics:_** [[TWikiPreferences]], [[TWikiPlugins]]
-
--- TWiki:Main/CrawfordCurrie - 15:45:58 03 March 2007
index 9fe2189..3ee7602 100644 (file)
@@ -31,6 +31,7 @@
         <li><a href="#=bookmark="> bookmark</a></li>
         <li><a href="#=return="> return</a></li>
         <li><a href="#=noform="> noform</a></li>
+        <li><a href="#=templatetopic="> templatetopic</a></li>
       </ul>
     </li>
   </ul>
@@ -216,6 +217,22 @@ Example of a custom form to save a comment to a new topic. When the topic is cre
   </div>
 </form>
 
+<a name="TemplateTopic"></a>
+
+### <a name="=templatetopic="></a> `templatetopic`
+
+Example of a form definition in a topic. The comment template is located in [[CommentPluginTemplateExample]].
+
+<a name="CommentDate1176024819"></a> [[TWikiContributor]] - 08 Apr 2007:
+
+templatetopic example comment output 1
+
+----
+
+<input name="comment_action" type="hidden" value="save" />
+<input name="comment_type" type="hidden" value="example" />
+<input name="comment_index" type="hidden" value="17" />
+
 ----
 
 - Bottom comment output 1 -- [[TWikiContributor]] - 26 Nov 2006
index 312c9f4..8fa561d 100644 (file)
@@ -224,7 +224,7 @@ Talk using TOC adding on end - TWiki:Main/FranzJosefSilli
 
 #### <a name="bookmark"></a> bookmark
 
-Talk using TOC adding on end - TWiki:Main/FranzJosefSilli
+Create a list of annotated bookmarks - TWiki:Main/FranzJosefSilli
 
     %TMPL:DEF{PROMPT:bookmark}%
     %TABLE{databg="#ffffff" tableborder="0" cellborder="0"}%
index 0015821..33c84ab 100644 (file)
@@ -4,7 +4,7 @@ Why does the topic revision not increase when I edit a topic?
 
 ## <a name="Answer:"></a> Answer:
 
-The same topic revision will be used when you save a topic again within a certain time frame (one hour by default). This is to prevent unnecessary topic revisions when you do several edit cycles in a row. Note that a new revision **_is_** created if another person edits the same topic, regardless of the time.
+The same topic revision will be used when you save a topic again within a certain time frame (one hour by default, configurable with configure item `{ReplaceIfEditedAgainWithin}`). This is to prevent unnecessary topic revisions when you do several edit cycles in a row. Note that a new revision **_is_** created if another person edits the same topic, regardless of the time.
 
 **_Back to:_** [[TWikiFAQ]]
 
index 775ad2f..4a83a89 100644 (file)
@@ -1,11 +1,17 @@
 # <a name="Edit Table Plugin"></a><a name=" Edit Table Plugin"></a> Edit Table Plugin
 
-This plugin allows you to edit TWiki tables using edit fields and drop down boxes. Tables have an **[ Edit table ]** button if preceeded by an `%EDITTABLE{...}%` variable. Each column can be a text field, a drop down box, a date field, etc. Multiple tables per topic are editable, but only one at a time can be edited.
+Edit TWiki tables in place, using edit fields and drop down boxes, without having to edit the complete topic.
+
+Simply add an **[ Edit table ]** button to an existing table by writing `%EDITTABLE{}%` directly above the table. This can be added to tables that are formatted with [[TablePlugin]]: add the `EDITTABLE` variable just above or below the `TABLE` tag. It can also be used without any `TABLE` tag.
+
+Customize entry fields by specifying the format: use a text field, a drop down box, a date field, radio buttons or checkboxes.
+
+Multiple tables per topic are editable, but only one at a time can be edited.
 
 <div>
   <ul>
     <li><a href="#Per Table Settings"> Per Table Settings</a><ul>
-        <li><a href="#Initial Values"> Initial Values</a></li>
+        <li><a href="#Using TWiki Variables in the For"> Using TWiki Variables in the Format Parameter</a></li>
         <li><a href="#Date Field Type"> Date Field Type</a></li>
       </ul>
     </li>
@@ -14,7 +20,7 @@ This plugin allows you to edit TWiki tables using edit fields and drop down boxe
     <li><a href="#Examples"> Examples</a></li>
     <li><a href="#Plugin Settings"> Plugin Settings</a></li>
     <li><a href="#Limitations and Known Issues"> Limitations and Known Issues</a></li>
-    <li><a href="#Plugin Installation Instructions"> Plugin Installation Instructions</a></li>
+    <li><a href="#Installation Instructions"> Installation Instructions</a></li>
     <li><a href="#License"> License</a></li>
     <li><a href="#Plugin Info"> Plugin Info</a></li>
   </ul>
@@ -22,86 +28,47 @@ This plugin allows you to edit TWiki tables using edit fields and drop down boxe
 
 ## <a name="Per Table Settings"></a> Per Table Settings
 
-Add a `%EDITTABLE{...}%` variable just before an existing table to make it editable, or add the variable anywhere in a topic to start a new table. Parameters:
+Add a `%EDITTABLE{...}%` variable just before an existing table to make it editable, or add the variable anywhere in a topic to start a new table.
 
-<table border="1" cellpadding="0" cellspacing="0">
-  <tr>
-    <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
-    <th bgcolor="#99CCCC"><strong> Comment </strong></th>
-    <th bgcolor="#99CCCC"><strong> Default </strong></th>
-  </tr>
-  <tr>
-    <td><code>header</code></td>
-    <td> Specify the header format of a new table like <code>"|*Food*|*Drink*|"</code>. Useful to start a table with only a button </td>
-    <td> (no header) </td>
-  </tr>
-  <tr>
-    <td><code>format</code></td>
-    <td> The format of one column when editing the table. A cell can be a text input field, or any of these edit field types:%BR% • Text input field (1 line):%BR%   <code>| text, &lt;size&gt;, &lt;initial value&gt; |</code> %BR% • Textarea input field:%BR%   <code>| textarea, &lt;rows&gt;x&lt;columns&gt;, &lt;initial value&gt; |</code> %BR% • Drop down box: %BR%   <code>| select, &lt;size&gt;, &lt;option 1&gt;, &lt;option 2&gt;, etc* |</code> %BR%   <code>*</code> only one item can be selected %BR% • Radio buttons: %BR%   <code>| radio, &lt;size*&gt;, &lt;option 1&gt;, &lt;option 2&gt;, etc |</code> %BR%   <code>*</code> size indicates the number of buttons per line in edit mode %BR% • Checkboxes: %BR%   <code>| checkbox, &lt;size*&gt;, &lt;option 1&gt;, &lt;option 2&gt;, etc |</code> %BR%   <code>*</code> size indicates the number of checkboxes per line in edit mode %BR% • Fixed label: %BR%   <code>| label, 0, &lt;label text&gt; |</code> %BR% • Row number: %BR%   <code>| row, &lt;offset&gt; |</code> %BR% • Date: %BR%   <code>| date, &lt;size&gt;, &lt;initial value&gt;, &lt;DHTML date format&gt; |</code> %BR%   <code>*</code> see <a href="http://www.dementia.org/twiki//view/TWiki/JSCalendarContrib/doc/html/reference.html" target="_top">Mishoo documentation</a> for more infos about the DHTML date format </td>
-    <td><code>"text, 16"</code> %BR% for all cells </td>
-  </tr>
-  <tr>
-    <td><code>changerows</code></td>
-    <td> Rows can be added and removed if <code>"on"</code>;<br /> Rows can be added but not removed if <code>"add"</code></td>
-    <td><code>CHANGEROWS</code> %BR% Plugin setting </td>
-  </tr>
-  <tr>
-    <td><code>quietsave</code></td>
-    <td> Quiet Save button is shown if <code>"on"</code>, hidden if <code>"off"</code></td>
-    <td><code>QUIETSAVE</code> %BR% Plugin setting </td>
-  </tr>
-  <tr>
-    <td><code>include</code></td>
-    <td> Other topic defining the EDITTABLE parameters. The first %EDITTABLE% in the topic is used. This is useful if you have many topics with the same table format and you want to update the format in one place. </td>
-    <td> (none) </td>
-  </tr>
-  <tr>
-    <td><code>helptopic</code></td>
-    <td> Topic name containing help text shown below the table when editing a table. The %STARTINCLUDE% and %STOPINCLUDE% variables can be used in the topic to specify what is shown. </td>
-    <td> (no help text) </td>
-  </tr>
-  <tr>
-    <td><code>headerislabel</code></td>
-    <td> Table header cells are read-only (labels) if <code>"on"</code>; header cells can be edited if <code>"off"</code> or "0" </td>
-    <td><code>"on"</code></td>
-  </tr>
-  <tr>
-    <td><code>editbutton</code></td>
-    <td> Set edit button text, e.g. <code>"Edit this table"</code>; set button image with alt text, e.g. <code>"Edit table, %PUBURL%/%TWIKIWEB%/TWikiDocGraphics/edittopic.gif"</code>; hide edit button at the end of the table with <code>"hide"</code> (Note: Button is automatically hidden if an edit button is present in a cell) </td>
-    <td><code>EDITBUTTON</code> %BR% Plugin setting </td>
-  </tr>
-</table>
+### <a name="Using TWiki Variables in the For"></a> Using TWiki Variables in the Format Parameter
 
-### <a name="Initial Values"></a> Initial Values
+TWiki variables like `%Y%` in `<initial value>` (of text input field) and `<label text>` (of fixed label) will get expanded when a new row is added.
 
-By default, variables in `<initial value>` (of text input field) and `<label text>` (of fixed label) get expanded when a new row is added. This can be used for example to add a timestamp to a label. You can escape characters if you do not want that:
+This is useful to write variables like dates into the table.
 
-<table border="1" cellpadding="0" cellspacing="0">
-  <tr>
-    <th bgcolor="#99CCCC"><strong> Text: </strong></th>
-    <th bgcolor="#99CCCC"><strong> To Escape: </strong></th>
-  </tr>
-  <tr>
-    <td><code>$quot</code></td>
-    <td> Double quote (<code>"</code>). Alternatively write <code>\"</code> to escape it </td>
-  </tr>
-  <tr>
-    <td><code>$percnt</code></td>
-    <td> Percent sign (<code>%</code>) </td>
-  </tr>
-  <tr>
-    <td><code>$dollar</code></td>
-    <td> Dollar sign (<code>$</code>) </td>
-  </tr>
-  <tr>
-    <td><code>$nop</code> or <code>$nop()</code></td>
-    <td> Is a "no operation" </td>
-  </tr>
-</table>
+> For example:
+>
+>     %EDITTABLE{ format="| label, 0, %SERVERTIME{"$day $mon $year $hour:$min"}% |" }%
+>
+> ... will get expanded to
+>
+> `29 Jun 2010 12:07`
+>
+> when the new row is created.
+
+To prevent variable expansion: escape the format variable with [[formatting tokens|TWiki/FormatTokens]] (particularly `$percnt`).
+
+> For example:
+>
+>     %EDITTABLE{ format="| text, 20, $percntY$percnt |" }%
+>
+> ... will create a new row with
+>
+> `$percntY$percnt`
+>
+> . In view mode this is temporarily translated to
+>
+> `%Y%`
+>
+> and subsequent rendered as %Y%.
+
+<a name="DateField"></a>
 
 ### <a name="Date Field Type"></a> Date Field Type
 
-<img src="http://www.dementia.org/twiki//view/EditTablePluginCalendarExample.gif" width="549" height="210" alt="Edit Table Calendar Example" /> The `date` field type allows one to choose a date with a popup calendar. Popup calendar works for Netscape 6.0 or better, all other Gecko-based browsers, Internet Explorer 5.0 or better for Windows, Opera 7 and Konqueror 3.1.2. The `...` button is inactive if the browser cannot support the popup calendar. It uses the nice [Mishoo DHTML calendar](http://dynarch.com/mishoo/calendar.epl), see also TWiki:Codev/JavaScriptDatePickerForForm <br />
+<img src="http://www.dementia.org/twiki//view/EditTablePluginCalendarExample.gif" width="638" height="250" alt="Edit Table Calendar Example" />
+
+The `date` field type allows one to choose a date with a popup calendar. Popup calendar works with all modern browsers. The date picker button is inactive if the browser cannot support the popup calendar or if javascript is disabled.
 
 ## <a name="Per Cell Settings"></a> Per Cell Settings
 
@@ -125,6 +92,8 @@ It is also possible to place the edit button inside a cell instead of default lo
         <li><input name="etaddrow" onclick="return(false);" type="submit" value="Add row" /> - add row to the table (if enabled) </li>
         <li><input name="etdelrow" onclick="return(false);" type="submit" value="Delete last row" /> - remove last row from the table (if enabled) </li>
         <li><input name="etcancel" onclick="return(false);" type="submit" value="Cancel" /> - cancel without saving and release edit lock </li>
+        <li><img src="http://www.dementia.org/twiki//view/btn_move.gif" /> - Move a row by clicking this button next to the row to be moved, then at a destination. </li>
+        <li><img src="http://www.dementia.org/twiki//view/btn_delete.gif" /> - Deletes the row next to this button. </li>
       </ul>
     </li>
   </ul>
@@ -164,51 +133,63 @@ Line before table: `%EDITTABLE{ format="| row, -1 | text, 20, init | select, 1,
 
 If this plugin is installed you will see an **[ Edit table ]** button above; if you were to click on it (please don't, use TWiki:Sandbox.EditTablePluginTesting for testing) you get this form:
 
-<form>
-  <table border="1" cellpadding="0" cellspacing="1">
-    <tr>
-      <th bgcolor="#99CCCC"> Nr </th>
-      <th bgcolor="#99CCCC"> Text field </th>
-      <th bgcolor="#99CCCC"> Drop down </th>
-      <th bgcolor="#99CCCC"> Mood </th>
-      <th bgcolor="#99CCCC"> Timestamp </th>
-    </tr>
+<a name="edittable1"></a>
+
+<div><input name="ettablenr" type="hidden" value="1" /><table border="1" cellpadding="0" cellspacing="0" id="default" rules="rows">
+    <thead>
+      <tr>
+        <th bgcolor="#6b7f93" valign="top"><a href="http://www.dementia.org/twiki/viewauth/TWiki/EditTablePlugin?ettablenr=1&amp;etedit=on&amp;etrows=3&amp;x=27&amp;y=13&amp;sortcol=0;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Nr<input name="etcell1x1" type="hidden" value="*Nr*" /></font></a></th>
+        <th bgcolor="#6b7f93" valign="top"><a href="http://www.dementia.org/twiki/viewauth/TWiki/EditTablePlugin?ettablenr=1&amp;etedit=on&amp;etrows=3&amp;x=27&amp;y=13&amp;sortcol=1;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Text field<input name="etcell1x2" type="hidden" value="*Text field*" /></font></a></th>
+        <th bgcolor="#6b7f93" valign="top"><a href="http://www.dementia.org/twiki/viewauth/TWiki/EditTablePlugin?ettablenr=1&amp;etedit=on&amp;etrows=3&amp;x=27&amp;y=13&amp;sortcol=2;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Drop down<input name="etcell1x3" type="hidden" value="*Drop down*" /></font></a></th>
+        <th bgcolor="#6b7f93" valign="top"><a href="http://www.dementia.org/twiki/viewauth/TWiki/EditTablePlugin?ettablenr=1&amp;etedit=on&amp;etrows=3&amp;x=27&amp;y=13&amp;sortcol=3;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Mood<input name="etcell1x4" type="hidden" value="*Mood*" /></font></a></th>
+        <th bgcolor="#6b7f93" valign="top"><a href="http://www.dementia.org/twiki/viewauth/TWiki/EditTablePlugin?ettablenr=1&amp;etedit=on&amp;etrows=3&amp;x=27&amp;y=13&amp;sortcol=4;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Timestamp<input name="etcell1x5" type="hidden" value="*Timestamp*" /></font></a></th>
+      </tr>
+    </thead>
     <tr>
-      <td bgcolor="#FFFFFF"> 1<input name="etcell2x1" type="hidden" value="1" /></td>
-      <td bgcolor="#FFFFFF"><input name="etcell2x2" size="20" type="text" value="hello table" /></td>
-      <td bgcolor="#FFFFFF"><select name="etcell2x3" size="1"><option selected>one</option>
+      <td bgcolor="#ffffff" valign="top"><span>1<input name="etcell2x1" type="hidden" value="1" /></span></td>
+      <td bgcolor="#ffffff" valign="top"><input name="etcell2x2" size="20" type="text" value="hello table" /></td>
+      <td bgcolor="#ffffff" valign="top"><select name="etcell2x3" size="1"><option selected>one</option>
           <option>two</option>
           <option>three</option>
           <option>four</option></select></td>
-      <td bgcolor="#FFFFFF"><input checked name="etcell2x4" type="radio" value=":-)" /> <img alt="smile" border="0" src="http://www.dementia.org/twiki//view/%WEB%/SmiliesPlugin/smile.gif" title="smile" /> <input name="etcell2x4" type="radio" value=":-I" /> <img alt="indifferent" border="0" src="http://www.dementia.org/twiki//view/%WEB%/SmiliesPlugin/indifferent.gif" title="indifferent" /> <input name="etcell2x4" type="radio" value=":-(" /> <img alt="frown" border="0" src="http://www.dementia.org/twiki//view/%WEB%/SmiliesPlugin/frown.gif" title="frown" /></td>
-      <td bgcolor="#FFFFFF"> 26 Jun 2002 12:30<input name="etcell2x5" type="hidden" value="26 Jun 2002 12:30" /></td>
+      <td bgcolor="#ffffff" valign="top"><input checked name="etcell2x4" type="radio" value=":-)" /> <img alt="smile" border="0" src="http://www.dementia.org/twiki//view/TWiki/SmiliesPlugin/smile.gif" title="smile" /> <input name="etcell2x4" type="radio" value=":-I" /> <img alt="indifferent" border="0" src="http://www.dementia.org/twiki//view/TWiki/SmiliesPlugin/indifferent.gif" title="indifferent" /> <input name="etcell2x4" type="radio" value=":-(" /> <img alt="frown" border="0" src="http://www.dementia.org/twiki//view/TWiki/SmiliesPlugin/frown.gif" title="frown" /></td>
+      <td bgcolor="#ffffff" valign="top"> 26 Jun 2002 12:30<input name="etcell2x5" type="hidden" value="26 Jun 2002 12:30" /></td>
     </tr>
     <tr>
-      <td bgcolor="#FFFF99"> 2<input name="etcell3x1" type="hidden" value="2" /></td>
-      <td bgcolor="#FFFF99"><input name="etcell3x2" size="20" type="text" value="" /></td>
-      <td bgcolor="#FFFF99"><select name="etcell3x3" size="1"><option>one</option>
+      <td bgcolor="#edf4f9" valign="top"><span>2<input name="etcell3x1" type="hidden" value="2" /></span></td>
+      <td bgcolor="#edf4f9" valign="top"><input name="etcell3x2" size="20" type="text" value="" /></td>
+      <td>
+        <p>
+        </p>
+      </td>
+      <td bgcolor="#edf4f9" valign="top"><select name="etcell3x3" size="1"><option>one</option>
           <option selected>two</option>
           <option>three</option>
           <option>four</option></select></td>
-      <td bgcolor="#FFFF99"><input name="etcell2x4" type="radio" value=":-)" /> <img alt="smile" border="0" src="http://www.dementia.org/twiki//view/%WEB%/SmiliesPlugin/smile.gif" title="smile" /> <input name="etcell2x4" type="radio" value=":-I" /> <img alt="indifferent" border="0" src="http://www.dementia.org/twiki//view/%WEB%/SmiliesPlugin/indifferent.gif" title="indifferent" /> <input checked name="etcell2x4" type="radio" value=":-(" /> <img alt="frown" border="0" src="http://www.dementia.org/twiki//view/%WEB%/SmiliesPlugin/frown.gif" title="frown" /></td>
-      <td bgcolor="#FFFF99"> 27 Jun 2002 12:40<input name="etcell3x5" type="hidden" value="27 Jun 2002 12:40" /></td>
+      <td bgcolor="#edf4f9" valign="top"><input name="etcell3x4" type="radio" value=":-)" /> <img alt="smile" border="0" src="http://www.dementia.org/twiki//view/TWiki/SmiliesPlugin/smile.gif" title="smile" /> <input name="etcell3x4" type="radio" value=":-I" /> <img alt="indifferent" border="0" src="http://www.dementia.org/twiki//view/TWiki/SmiliesPlugin/indifferent.gif" title="indifferent" /> <input checked name="etcell3x4" type="radio" value=":-(" /> <img alt="frown" border="0" src="http://www.dementia.org/twiki//view/TWiki/SmiliesPlugin/frown.gif" title="frown" /></td>
+      <td bgcolor="#edf4f9" valign="top"> 27 Jun 2002 12:40<input name="etcell3x5" type="hidden" value="27 Jun 2002 12:40" /></td>
     </tr>
-  </table><input name="etsave" onclick="return(false);" type="submit" value="Save table" /> <input name="etqsave" onclick="return(false);" type="submit" value="Quiet save" /> <input name="etaddrow" onclick="return(false);" type="submit" value="Add row" /> <input name="etdelrow" onclick="return(false);" type="submit" value="Delete last row" /> <input name="etcancel" onclick="return(false);" type="submit" value="Cancel" /> (demo only, these buttons do not work) </form>
+  </table><input name="etrows" type="hidden" value="3" /> <input id="etsave" name="etsave" type="submit" value="Save table" /> <input id="etqsave" name="etqsave" type="submit" value="Quiet save" /> <input id="etaddrow" name="etaddrow" type="submit" value="Add row" /> <input id="etdelrow" name="etdelrow" type="submit" value="Delete last row" /> <input id="etcancel" name="etcancel" type="submit" value="Cancel" /></div>
 
 The following example shows a simple table with key/value rows. The default edit field type for the value column is a text field. This is overloaded by a selector for the Gender, and a date picker for the DOB. This is typically used by TWiki applications where new topics with tables are created based on a template topic.
 
-<table>
+<table cellpadding="6" style="background: #f2f2f2">
+  <tr>
+    <th> You type: </th>
+    <th> You get: </th>
+    <th> Table in edit mode: </th>
+  </tr>
   <tr>
-    <td valign="top"> You type: <pre>
-%EDITTABLE{ format="| label | text, 40 |" }%
+    <td valign="top"><pre>
+%EDITTABLE{ format="| label | text, 40 |" changerows="off" }%
 |*Key*|*Value*|
 | Name: | John Smith |
 | Gender: | M %EDITCELL{select, 1, , F, M}% |
 | DOB: | 1999/12/31 %EDITCELL{date, 10}% |
 | City: | New York |
 </pre></td>
-    <td valign="top"> Screenshot: <img alt="EDITCELL Example in view mode" height="141" src="http://www.dementia.org/twiki//view/ScreenshotEditCell1.gif" width="149" /></td>
-    <td valign="top"> Screenshot in edit mode: <img alt="EDITCELL Example in edit mode" height="164" src="http://www.dementia.org/twiki//view/ScreenshotEditCell2.gif" width="276" /></td>
+    <td valign="top"><img alt="EDITCELL Example in view mode" height="172" src="http://www.dementia.org/twiki//view/ScreenshotEditCell1.gif" width="150" /></td>
+    <td valign="top"><img alt="EDITCELL Example in edit mode" height="198" src="http://www.dementia.org/twiki//view/ScreenshotEditCell2.gif" width="436" /></td>
   </tr>
 </table>
 
@@ -222,15 +203,26 @@ Plugin settings are stored as preferences variables. To reference a plugin setti
 - Set DEBUG to 1 to get debug messages in `data/debug.txt`. Default: `0`
   - Set DEBUG = 0
 
+- Set JAVASCRIPTINTERFACE to 1 to be able to directly move and delete row without page refresh.
+  - Set JAVASCRIPTINTERFACE = 1
+
 - Default for change rows flag: `on`, `off`, `add`
   - Set CHANGEROWS = on
 
 - Default flag for quiet save option: `on` to show the Quiet Save button, `off` to hide
   - Set QUIETSAVE = on
 
-- Default edit button: Specify `button text`, or specify `alternate text, image URL`
-  - #Set EDITBUTTON = Edit table
-  - Set EDITBUTTON = Edit this table, ![edittable.gif](http://www.dementia.org/twiki//view/edittable.gif)
+- Default edit button: Specify `button text`, or specify `alternate text, image URL`. Note: Texts inside `%MAKETEXT{}%` are translated into other languages.
+  - #Set EDIT\_BUTTON = Edit table
+  - Set EDIT\_BUTTON = Edit this table, ![edittable.gif](http://www.dementia.org/twiki//view/edittable.gif)
+  - Set SAVE\_BUTTON = Save table
+  - Set QUIET\_SAVE\_BUTTON = Quiet save
+  - Set ADD\_ROW\_BUTTON = Add row
+  - Set DELETE\_LAST\_ROW\_BUTTON = Delete last row
+  - Set CANCEL\_BUTTON = Cancel
+
+- Default help texts
+  - Set INCLUDED\_TOPIC\_DOES\_NOT\_EXIST = <span>Warning: 'include' topic does not exist!</span>
 
 **_Note:_** The Plugin uses base settings like date format, language and style from the [[JSCalendarContrib]].
 
@@ -242,55 +234,13 @@ Plugin settings are stored as preferences variables. To reference a plugin setti
 - You cannot put two `%EDITTABLE{}%` statements on the same line in the source
 - You can include %-vars now in select values, by quoting them with &lt;nop&gt;, as in %&lt;nop&gt;X% for %X%, say for instance: <br />`select,1,%<nop>X%,%<nop>Y%`
 
-## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
-
-**_Note:_** You do not need to install anything on the browser to use this Plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.
+## <a name="Installation Instructions"></a> Installation Instructions
 
 - Download the ZIP file from the Plugin web (see below)
-- Unzip <code>**%TOPIC%.zip**</code> in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0">
-  <tr>
-    <th bgcolor="#99CCCC"><strong> File: </strong></th>
-    <th bgcolor="#99CCCC"><strong> Description: </strong></th>
-  </tr>
-  <tr>
-    <td><code><b>data/TWiki/%TOPIC%.txt</b></code></td>
-    <td> Plugin topic </td>
-  </tr>
-  <tr>
-    <td><code><b>data/TWiki/%TOPIC%.txt,v</b></code></td>
-    <td> Plugin topic repository </td>
-  </tr>
-  <tr>
-    <td><code><b>lib/TWiki/Plugins/%TOPIC%.pm</b></code></td>
-    <td> Plugin Perl module </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/%TOPIC%/edittable.gif</b></code></td>
-    <td> Edit table button image </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/%TOPIC%/*.gif</b></code></td>
-    <td> Screenshots and Mishoo DHTML calendar images </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/%TOPIC%/README</b></code></td>
-    <td> Mishoo DHTML calendar README </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/%TOPIC%/release-notes.html</b></code></td>
-    <td> Mishoo DHTML calendar release notes </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/%TOPIC%/*.js</b></code></td>
-    <td> Mishoo DHTML calendar JavaScript files </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/%TOPIC%/calendar-system.css</b></code></td>
-    <td> Mishoo DHTML calendar stylesheet </td>
-  </tr>
-</table>
+- Unzip <code>**%TOPIC%.zip**</code> in your ($TWIKI\_ROOT) directory.
+- Alternatively,
+  - Manually resolve the dependencies listed below. None
 - The Plugin depends on the `viewauth` script to authenticate the user. As described in [[TWikiAccessControl]], copy the `view` script to `viewauth` (or better, create a symbolic link) and add `viewauth` to the list of authenticated scripts in the `.htaccess` file.
-- The Mishoo DHTML calendar 0.9.5 is preinstalled and should work without any configuration. If you wish to use another language, specify the in the Plugin settings, or create a new language files, attach it to the Plugin topic, and change the Plugin settings
 - (Dakar) Visit `configure` in your TWiki installation, and enable the plugin in the \{Plugins\} section.
 - Test if the Plugin is correctly installed:
   - Check above example if there is an **[ Edit table ]** button below the table in above example
@@ -299,18 +249,17 @@ Plugin settings are stored as preferences variables. To reference a plugin setti
 ## <a name="License"></a> License
 
 - The Edit Table Plugin is released under the [GPL](http://www.gnu.org/licenses/gpl.html)
-- The [Mishoo DHTML calendar](http://dynarch.com/mishoo/calendar.epl) bundled with this Plugin was created by Mihai Bazon and is released under the [LGPL](http://www.gnu.org/licenses/lgpl.html) -- thanks Mihai for the great tool :-)
 
 ## <a name="Plugin Info"></a> Plugin Info
 
 <table border="1" cellpadding="0" cellspacing="0">
   <tr>
     <td align="right"> Plugin Author: </td>
-    <td><a href="http://www.structuredwikis.com/" target="_top">Peter Thoeny</a></td>
+    <td> TWiki:Main/PeterThoeny </td>
   </tr>
   <tr>
     <td align="right"> Copyright: </td>
-    <td> © 2002-2006, TWiki:Main.PeterThoeny </td>
+    <td> © 2002-2007, TWiki:Main.PeterThoeny (<a href="http://www.twiki.net/" target="_top">TWIKI.NET</a>) and TWiki Contributors </td>
   </tr>
   <tr>
     <td align="right"> License: </td>
@@ -318,13 +267,45 @@ Plugin settings are stored as preferences variables. To reference a plugin setti
   </tr>
   <tr>
     <td align="right"> Plugin Version: </td>
-    <td> 12327 </td>
+    <td> 4.7.10 (08 Jan 2008) </td>
   </tr>
   <tr>
     <td align="right"> Change History: </td>
     <td>  </td>
   </tr>
   <tr>
+    <td align="right"> 25 Dec 2007: </td>
+    <td> 4.7.1: Arthur Clemens: Added warning if <code>include</code> parameter topic does not exist. </td>
+  </tr>
+  <tr>
+    <td align="right"> 22 Dec 2007: </td>
+    <td> 4.7: Arthur Clemens: Changed handling of escaped variables. To escape TWiki variable, use formatting tokens such as <code>$percnt</code>. </td>
+  </tr>
+  <tr>
+    <td align="right"> 16 Dec 2007: </td>
+    <td> 4.6: Kenneth Lavrsen: The plugin prevents [[Main/TablePlugin]] from initsorting the table being edited. This is done by temporarily appending the attribute disableallsort="on" to the TABLE tag of a table being edited. Additionally all header sorting is disabled while editing a table by setting a hidden formfield <code>sort</code> to "off". Disabling sorting while editing is needed now that the [[Main/EditTablePlugin]] supports moving rows up and down. </td>
+  </tr>
+  <tr>
+    <td align="right"> 01 Dec 2007: </td>
+    <td> 4.3: Arthur Clemens: added support for [[Main/TablePlugin]] <code>headerrows</code> and <code>footerrows</code>; updated edit button </td>
+  </tr>
+  <tr>
+    <td align="right"> 16 Oct 2007: </td>
+    <td> 4.2: Arthur Clemens: refactoring, bug fixes. </td>
+  </tr>
+  <tr>
+    <td align="right"> 07 Oct 2007: </td>
+    <td> 15182: PTh: Added [[TWiki/VarEDITTABLE]] to have it listed in [[TWiki/TWikiVariables]]</td>
+  </tr>
+  <tr>
+    <td align="right"> 15 Mar 2007: </td>
+    <td> Arthur Clemens: Fixed eating of double newlines; icons for javascript buttons and interface improvements. By default the javascript interface is turned off, set <code>JAVASCRIPTINTERFACE</code> to use it in edit mode. </td>
+  </tr>
+  <tr>
+    <td align="right"> 05 Mar 2007: </td>
+    <td> Byron Darrah: Added ability to dynamically move and delete rows. </td>
+  </tr>
+  <tr>
     <td align="right"> 12 Oct 2006: </td>
     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item2982" rel="nofollow">Item2982</a> Use default date format from [[Main/JSCalendarContrib]]</td>
   </tr>
@@ -346,7 +327,7 @@ Plugin settings are stored as preferences variables. To reference a plugin setti
   </tr>
   <tr>
     <td align="right"> 16 Sep 2004: </td>
-    <td> Added radio buttons and checkbox controls; escaped "|" pipe symbol found in input fields to preserve tables </td>
+    <td> Added radio buttons and checkbox controls; escaped "%VBAR%" pipe symbol found in input fields to preserve tables </td>
   </tr>
   <tr>
     <td align="right"> 01 Aug 2004: </td>
@@ -458,6 +439,6 @@ Plugin settings are stored as preferences variables. To reference a plugin setti
   </tr>
 </table>
 
-**_Related Topics:_** [[TWikiPreferences]], [[TWikiPlugins]]
+**_Related Topics:_** [[VarEDITTABLE]], [[TWikiPreferences]], [[TWikiPlugins]]
 
--- TWiki:Main/PeterThoeny - 02 Oct 2006
+-- TWiki:Main/PeterThoeny - 07 Oct 2007
index e004d24..f7570a5 100644 (file)
@@ -12,6 +12,19 @@ To create your own Plugin:
 
 (none)
 
+## <a name="Plugin Settings"></a> Plugin Settings
+
+Plugin settings are stored as preferences variables. To reference a plugin setting write <code>**%&lt;plugin&gt;\_&lt;setting&gt;%**</code>, i.e. <code>**%EMPTYPLUGIN\_SHORTDESCRIPTION%**</code>
+
+- One line description, is shown in the [[TextFormattingRules]] topic:
+  - Set SHORTDESCRIPTION = Empty Plugin used as a template for new Plugins
+
+- Your own setting, for example:
+  - Set EXAMPLE = got it!
+
+- Debug plugin: ( TWiki sets `$debug` in your plugin. See output in `data/debug.txt`.)
+  - Set DEBUG = 0
+
 ## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
 
 - This plugin is preinstalled, you do not need to install it.
@@ -25,7 +38,7 @@ To create your own Plugin:
   </tr>
   <tr>
     <td align="right"> Copyright: </td>
-    <td> © 2001-2006, [[TWiki/TWikiContributor]]</td>
+    <td> © 2001-2007, [[TWiki/TWikiContributor]]</td>
   </tr>
   <tr>
     <td align="right"> License: </td>
@@ -33,13 +46,17 @@ To create your own Plugin:
   </tr>
   <tr>
     <td align="right"> Plugin Version: </td>
-    <td> 01 Feb 2006 </td>
+    <td> 15942 (22 Jan 2008) </td>
   </tr>
   <tr>
     <td align="right"> Change History: </td>
     <td>  </td>
   </tr>
   <tr>
+    <td align="right"> 20 May 2007 </td>
+    <td> Added renderWikiWordHandler </td>
+  </tr>
+  <tr>
     <td align="right"> 01 Feb 2006: </td>
     <td> Dakar changes </td>
   </tr>
@@ -60,16 +77,8 @@ To create your own Plugin:
     <td> $TWiki::Plugins::VERSION 1.1 </td>
   </tr>
   <tr>
-    <td align="right"> CPAN Dependencies: </td>
-    <td> none </td>
-  </tr>
-  <tr>
-    <td align="right"> Other Dependencies: </td>
-    <td> none </td>
-  </tr>
-  <tr>
-    <td align="right"> Perl Version: </td>
-    <td> 5.005 </td>
+    <td align="right"> Dependencies: </td>
+    <td> %$DEPENDENCIES </td>
   </tr>
   <tr>
     <td align="right"> TWiki:Plugins/Benchmark: </td>
index b593369..7f284fb 100644 (file)
@@ -1,3 +1,7 @@
+# <a name="File Attachments"></a> File Attachments
+
+_Each topic can have one or more files of any type attached to it by using the Attach screen to upload (or download) files from your local PC. Attachments are stored under revision control: uploads are automatically backed up; all previous versions of a modified file can be retrieved._
+
 <div>
   <ul>
     <li><a href="#File Attachments"> File Attachments</a><ul>
   </ul>
 </div>
 
-# <a name="File Attachments"></a> File Attachments
-
-_Each topic can have one or more files of any type attached to it by using the Attach screen to upload (or download) files from your local PC. Attachments are stored under revision control: uploads are automatically backed up; all previous versions of a modified file can be retrieved._
-
 ## <a name="What Are Attachments Good For?"></a> What Are Attachments Good For?
 
 File Attachments can be used to archive data, or to create powerful customized groupware solutions, like file sharing and document management systems, and quick Web page authoring.
@@ -120,7 +120,7 @@ Files attached to a topic are displayed in a directory table, displayed at the b
       <th align="center" bgcolor="#ffffff" style="text-align: center; vertical-align: middle" valign="middle"><a href="%TOPIC%?sortcol=6;table=1;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#0066cc">Comment</font></a></th>
     </tr>
     <tr>
-      <td align="center" bgcolor="#ffffff" style="text-align: center; vertical-align: top" valign="top"><img align="top" alt="txt" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/txt.gif" width="16" /><span>txt</span></td>
+      <td align="center" bgcolor="#ffffff" style="text-align: center; vertical-align: top" valign="top"><img align="top" alt="txt" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/txt.gif" width="16" /><span>txt</span></td>
       <td align="left" bgcolor="#ffffff" style="text-align: left; vertical-align: top" valign="top"><a href="/twiki4/MAIN/bin/viewfile/TWiki/FileAttachment?rev=;filename=Sample.txt">Sample.txt</a></td>
       <td align="left" bgcolor="#ffffff" style="text-align: left; vertical-align: top" valign="top"><a href="/twiki4/MAIN/bin/attach/TWiki/FileAttachment?filename=Sample.txt&revInfo=1" rel="nofollow" title="change, update, previous revisions, move, delete...">manage</a></td>
       <td align="right" bgcolor="#ffffff" style="text-align: right; vertical-align: top" valign="top"> 0.1 K </td>
@@ -129,7 +129,7 @@ Files attached to a topic are displayed in a directory table, displayed at the b
       <td align="left" bgcolor="#ffffff" style="text-align: left; vertical-align: top" valign="top"> Just a sample </td>
     </tr>
     <tr>
-      <td align="center" bgcolor="#ffffff" style="text-align: center; vertical-align: top" valign="top"><img align="top" alt="gif" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/gif.gif" width="16" /><span>gif</span></td>
+      <td align="center" bgcolor="#ffffff" style="text-align: center; vertical-align: top" valign="top"><img align="top" alt="gif" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/gif.gif" width="16" /><span>gif</span></td>
       <td align="left" bgcolor="#ffffff" style="text-align: left; vertical-align: top" valign="top"><a href="/twiki4/MAIN/bin/viewfile/TWiki/FileAttachment?rev=;filename=Smile.gif">Smile.gif</a></td>
       <td align="left" bgcolor="#ffffff" style="text-align: left; vertical-align: top" valign="top"><a href="/twiki4/MAIN/bin/attach/TWiki/FileAttachment?filename=Smile.gif&revInfo=1" rel="nofollow" title="change, update, previous revisions, move, delete...">manage</a></td>
       <td align="right" bgcolor="#ffffff" style="text-align: right; vertical-align: top" valign="top"> 0.1 K </td>
index 975241b..2a94a20 100644 (file)
@@ -2,7 +2,7 @@ Normally, if you make subsequent edits within a one hour period (configuration i
 
 The "Force New Revision" checkbox is a way to force it to create a separate revision each time you save.
 
-The [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] variable `FORCENEWREVISIONCHECKBOX` controls whether this is checked by default or not.
+The [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]] variable `FORCENEWREVISIONCHECKBOX` controls whether this is checked by default or not.
 
 On a related note, you can force **_every_** save to be a new revision number by setting `ReplaceIfEditedAgainWithin` to 0.
 
diff --git a/TWiki/FormatTokens.mdwn b/TWiki/FormatTokens.mdwn
new file mode 100644 (file)
index 0000000..dda7107
--- /dev/null
@@ -0,0 +1,28 @@
+## <a name="Formatting Tokens"></a> Formatting Tokens
+
+TWiki defines some standard special tokens that can be used to replace characters in some parameters - notably those to [[FormattedSearch]] and [[IfStatements]] - to defer evaluation of the parameter until later. These special tokens are often called "escapes", because they allow the character to "escape" from its normal meaning.
+
+<table border="1" cellpadding="0" cellspacing="0">
+  <tr>
+    <td><code>$n</code> or <code>$n()</code></td>
+    <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
+  </tr>
+  <tr>
+    <td><code>$nop</code> or <code>$nop()</code></td>
+    <td> Is a "no operation". This variable gets removed; useful for nested search </td>
+  </tr>
+  <tr>
+    <td><code>$quot</code></td>
+    <td> Double quote (<code>"</code>) (\" also works) </td>
+  </tr>
+  <tr>
+    <td><code>$percnt</code></td>
+    <td> Percent sign (<code>%</code>) </td>
+  </tr>
+  <tr>
+    <td><code>$dollar</code></td>
+    <td> Dollar sign (<code>$</code>) </td>
+  </tr>
+</table>
+
+If you ever find yourself needing to escape an escape, you can use `$dollar` to escape the leading dollar, thus: `$dollarpercnt`.
index 81fb00c..012cf38 100644 (file)
@@ -1,3 +1,9 @@
+# <a name="TWiki Formatted Search"></a> TWiki Formatted Search
+
+_Inline search feature allows flexible formatting of search result_
+
+The default output format of a <code>[[%SEARCH{...}%|Main/VarSEARCH]]</code> is a table consisting of topic names and topic summaries. Use the `format="..."` parameter to customize the search result. The format parameter typically defines a bullet or a table row containing variables, such as `%SEARCH{ "food" format="| $topic | $summary |" }%`. See <code>[[%SEARCH{...}%|Main/VarSEARCH]]</code> for other search parameters, such as `separator=""`.
+
 <div>
   <ul>
     <li><a href="#TWiki Formatted Search"> TWiki Formatted Search</a><ul>
   </ul>
 </div>
 
-# <a name="TWiki Formatted Search"></a> TWiki Formatted Search
-
-_Inline search feature allows flexible formatting of search result_
-
-The default output format of a <code>[[%SEARCH{...}%|Main/VarSEARCH]]</code> is a table consisting of topic names and topic summaries. Use the `format="..."` parameter to customize the search result. The format parameter typically defines a bullet or a table row containing variables, such as `%SEARCH{ "food" format="| $topic | $summary |" }%`. See <code>[[%SEARCH{...}%|Main/VarSEARCH]]</code> for other search parameters, such as `separator=""`.
-
 ## <a name="Syntax"></a> Syntax
 
 Two parameters can be used to specify a customized search result:
@@ -82,26 +82,6 @@ Variables that can be used in the header string:
     <td><code>$web</code></td>
     <td> Name of the web </td>
   </tr>
-  <tr>
-    <td><code>$n</code> or <code>$n()</code></td>
-    <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
-  </tr>
-  <tr>
-    <td><code>$nop</code> or <code>$nop()</code></td>
-    <td> Is a "no operation". This variable gets removed; useful for nested search </td>
-  </tr>
-  <tr>
-    <td><code>$quot</code></td>
-    <td> Double quote (<code>"</code>). Alternatively write <code>\"</code> to escape it </td>
-  </tr>
-  <tr>
-    <td><code>$percnt</code></td>
-    <td> Percent sign (<code>%</code>) </td>
-  </tr>
-  <tr>
-    <td><code>$dollar</code></td>
-    <td> Dollar sign (<code>$</code>) </td>
-  </tr>
 </table>
 
 ### <a name="2. &lt;code&gt;format=&quot;...&quot;&lt;/code&gt; parameter"></a> 2. `format="..."` parameter
@@ -153,11 +133,11 @@ Variables that can be used in the format string:
   </tr>
   <tr>
     <td><code>$date</code></td>
-    <td> Time stamp of last topic update, e.g. <code>29 Jun 2010 - 16:02</code></td>
+    <td> Time stamp of last topic update, e.g. <code>29 Jun 2010 - 16:07</code></td>
   </tr>
   <tr>
     <td><code>$isodate</code></td>
-    <td> Time stamp of last topic update, e.g. <code>2010-06-29T16:02Z</code></td>
+    <td> Time stamp of last topic update, e.g. <code>2010-06-29T16:07Z</code></td>
   </tr>
   <tr>
     <td><code>$rev</code></td>
@@ -173,7 +153,7 @@ Variables that can be used in the format string:
   </tr>
   <tr>
     <td><code>$wikiusername</code></td>
-    <td> Wiki user name of last topic update, like <code>Main.JohnSmith</code></td>
+    <td> Wiki user name of last topic update, like <code>%USERSWEB%.JohnSmith</code></td>
   </tr>
   <tr>
     <td><code>$createdate</code></td>
@@ -189,7 +169,7 @@ Variables that can be used in the format string:
   </tr>
   <tr>
     <td><code>$createwikiusername</code></td>
-    <td> Wiki user name of topic revision 1, e.g. <code>Main.JohnSmith</code></td>
+    <td> Wiki user name of topic revision 1, e.g. <code>%USERSWEB%.JohnSmith</code></td>
   </tr>
   <tr>
     <td><code>$summary</code></td>
@@ -243,26 +223,6 @@ Variables that can be used in the format string:
     <td><code>$count(reg-exp)</code></td>
     <td> Count of number of times a regular expression pattern appears in the text of a topic (does not search meta data). Follows guidelines for use and limitations outlined above under <code>$pattern(reg-exp)</code>. Example: <code>$count(.*?(---[+][+][+][+]) .*)</code> counts the number of &lt;H4&gt; headers in a page. </td>
   </tr>
-  <tr>
-    <td><code>$n</code> or <code>$n()</code></td>
-    <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
-  </tr>
-  <tr>
-    <td><code>$nop</code> or <code>$nop()</code></td>
-    <td> Is a "no operation". This variable gets removed; useful for nested search </td>
-  </tr>
-  <tr>
-    <td><code>$quot</code></td>
-    <td> Double quote (<code>"</code>). Alternatively write <code>\"</code> to escape it </td>
-  </tr>
-  <tr>
-    <td><code>$percnt</code></td>
-    <td> Percent sign (<code>%</code>) </td>
-  </tr>
-  <tr>
-    <td><code>$dollar</code></td>
-    <td> Dollar sign (<code>$</code>) </td>
-  </tr>
 </table>
 
 ## <a name="Examples"></a> Examples
index eedae2c..cd0a98a 100644 (file)
@@ -5,8 +5,8 @@ The box at the top or sidebar of each page, also called Jump box.
 Enter a topic name to quickly jump to the topic, for example:
 
 - **WebNotify** to jump to WebNotify in the current web
-- **Main.WebNotify** to jump to WebNotify in the Main web
-- **Main.** to jump to the home of the Main web
+- **%USERSWEB%.WebNotify** to jump to WebNotify in the %USERSWEB% web
+- **%USERSWEB%.** to jump to the home of the %USERSWEB% web
 - **BrandNewTopic** to jump to a non existing topic in the current web, which is useful to create orphaned topics
 
 Enter part of a topic name to get a list of similar topics, for example:
@@ -14,7 +14,7 @@ Enter part of a topic name to get a list of similar topics, for example:
 - **faq** to get
 # TWiki Installation Error
 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
-- **Main.users** to jump to the Main web from any web, and get a list of topics about users (all in one step)
+- **%USERSWEB%.users** to jump to the %USERSWEB% web from any web, and get a list of topics about users (all in one step)
 
 **_%T% Tip:_** Entering part of a topic name is a simple, yet powerful way to quickly navigate to content of interest, also in a large wiki.
 
index 0e8dc33..4f2ed4a 100644 (file)
 
 - For **external site links**, you can type URLs directly into the text - `http://etcete.ra/...` - it'll be clear to anyone where they're headed on click.
 
-- TWiki is intended for world-wide use, and an internationally understood date format like <code>**01 Sep 2003**</code> or <code>**2003/09/01**</code> is preferred. It's clearer than the xx/xx/xx format, where a date like 9/1/01 can mean either Jan or Sep, depending on the local conventions of the readers. For months, use the first three letters: Jan, Feb, Mar, Apr,...
+- TWiki is intended for world-wide use, and an internationally understood date format like <code>**01 Sep 2010**</code> or <code>**2010-09-01**</code> is preferred. It's clearer than the xx/xx/xx format, where a date like 9/1/01 can mean either Jan or Sep, depending on the local conventions of the readers. For months, use the first three letters: Jan, Feb, Mar, Apr,...
 
 - **TIP:** Check the source when you want to find out how something is formatted: click <code>**Edit**</code> on the lower toolbar. To see earlier versions, click <code>**More**</code>, then check <code>**Raw text format**</code> and click <code>**View revision**</code>. A bit of HTML experience can't hurt, but you'll soon see with [[TWikiShorthand]] how far that is from necessary.
 
 **_Related Topics:_** [[UserDocumentationCategory]]
+
+-- **_Contributors:_** TWiki:Main.MikeMannix, TWiki:Main.PeterThoeny
index 71b9f9b..5d3a6c0 100644 (file)
@@ -30,7 +30,7 @@ Two sections are defined:
 
 ### <a name="Displaying the Parent - Current"></a><a name="Displaying the Parent - Current "></a> Displaying the Parent - Current - Children block
 
-> %INCLUDE{"%TWIKIWEB%.HierarchicalNavigation" section="all"}%
+> %INCLUDE{"%SYSTEMWEB%.HierarchicalNavigation" section="all"}%
 
 generates:
 
@@ -44,7 +44,7 @@ When included in [[WebLeftBar]] (using default Pattern skin) this is styled to:
 ### <a name="Displaying child topics"></a> Displaying child topics
 
 > *Child topics:*
->     %INCLUDE{"%TWIKIWEB%.HierarchicalNavigation" section="children"}%
+>     %INCLUDE{"%SYSTEMWEB%.HierarchicalNavigation" section="children"}%
 
 generates:
 
index 7d36b17..46ad312 100644 (file)
@@ -1,4 +1,4 @@
-# <a name="=IF= Statements"></a> `IF` Statements
+# <a name="IF Statements"></a> IF Statements
 
 The `%IF%` construct gives TWiki the power to include content in topics based on the value of simple expressions.
 
@@ -6,45 +6,30 @@ The `%IF%` construct gives TWiki the power to include content in topics based on
 
 In the example above, if CONDITION evaluates to TRUE, then THEN will be included in the topic; otherwise ELSE will be included.
 
-What can be included in the THEN and ELSE parameters is obviously limited by standard TWiki syntax for parameters.
+Note that because of the way TWiki evaluates, then whatever is in the THEN and ELSE parameters will already have been expanded by the time the condition is actually evaluated. The standard [[FormatTokens]] can be used in the THEN and ELSE parameters when you need to delay evaluation of (for example) a TWiki variable.
 
-The basic syntax of a condition is as follows:
+The basic syntax of a condition is the same as [[the syntax used for queries|Main/QuerySearch]], with the addition of the following special operators:
 
-    expr ::= '(' expr ')' ;
-    expr ::= andexpr | andexpr 'or' expr ;
-    andexpr ::= notexpr | notexpr 'and' andexpr ;
-    notexpr ::= basexpr | 'not' baseexpr ;
-    basexpr ::= atom | uop atom | atom bop basexpr ;
-    uop ::= 'context' | 'defined' | '$' ;
-    bop ::= '=' | '!=' | '>' | '<' | '>=' | '<=' ;
-    atom ::= context identifier, TWiki variable name, single-quoted string, or configuration item
 <table border="1" cellpadding="0" cellspacing="0">
   <tr>
-    <th bgcolor="#99CCCC" colspan="2"><strong> Operators </strong></th>
-  </tr>
-  <tr>
-    <td> and </td>
-    <td> True if both sides are true </td>
-  </tr>
-  <tr>
-    <td> or </td>
-    <td> True if one or other side is true </td>
+    <td> context </td>
+    <td> True if the current context is set (see below) </td>
   </tr>
   <tr>
-    <td> not </td>
-    <td> negate the following expression </td>
+    <td> allows </td>
+    <td><code>'X' allows 'Y'</code> is true if web/topic 'X' exists and allows access mode 'Y' for the current user. Web access rights are only checked if there is no topic called 'X'. </td>
   </tr>
   <tr>
-    <td> =, != </td>
-    <td> String comparison </td>
+    <td> istopic </td>
+    <td><code>istopic 'X'</code> is true if topic 'X' exists </td>
   </tr>
   <tr>
-    <td> &lt;, &gt;, &lt;=, &gt;= </td>
-    <td> Number comparison (there is no explicit numeric =) </td>
+    <td> isweb </td>
+    <td><code>isweb 'X'</code> is true if web 'X' exists </td>
   </tr>
   <tr>
-    <td> context </td>
-    <td> True if the current context is set (see below) </td>
+    <td> ingroup </td>
+    <td><code>'X' ingroup 'Y'</code> is true if user 'X' is in group 'Y' </td>
   </tr>
   <tr>
     <td> defined </td>
@@ -52,29 +37,68 @@ The basic syntax of a condition is as follows:
   </tr>
   <tr>
     <td> $ </td>
-    <td> expands a URL parameter or [[Main/TWikiVariables]]. Plugin handlers <strong>are not called</strong>. Built-in variables and user-defined preferences are supported. You can pass a limited subset of parameters to TWiki variables by enclosing the variable name in single quotes; for example, <code>$ 'VARIABLE{value}'</code>. The <code>'VARIABLE{value}'</code> string may <strong>not</strong> contain quotes (' or "). </td>
+    <td> expands a URL parameter or [[Main/TWikiVariables]] name. Plugin handlers <strong>are not called</strong>. Built-in variables and user-defined preferences are supported. You can pass a limited subset of parameters to TWiki variables by enclosing the variable name in single quotes; for example, <code>$ 'VARIABLE{value}'</code>. The <code>'VARIABLE{value}'</code> string may <strong>not</strong> contain quotes (' or "). </td>
+  </tr>
+  <tr>
+    <td> {X} </td>
+    <td> expands to the value of the configuration variable {X} - for example, <code>{ScriptUrlPath}</code></td>
   </tr>
 </table>
 
-examples:
+**_Examples:_**
+
+1. TWiki variable defined or not
 
-    TWiki variable defined or not
     %IF{"defined WIKINAME" then="WIKINAME is defined" else="WIKINAME is not defined"}%
 
+2. Compare TWiki variable
+
     You are %IF{ "$ WIKINAME='TWikiGuest' and not defined OPEN_DAY" then="not" }% allowed to
     %IF{ "context view" then="view" else="edit"}% this TWiki today.
 
-    URL parameter
-    %IF{ "defined search" then="Search: %URLPARAM{search}%" else="No search passed in"}%
+3. URL parameter
 
-    Configuration item set or not
-    %IF{ "{AntiSpam}{HideUserDetails}" then="User details are hidden" }%
+    %IF{ "defined search" then="Search: $percntURLPARAM{search}$percnt" else="No search passed in"}%
+
+4. Range test on URL parameter
 
     url param t is %IF{ "0 < $ t and $ t < 1000" then="in" else="out of"}% range.
 
-    Text comparison
+5. Text comparison of URL parameter
+
     %IF{ "$'URLPARAM{scope}'='text'" then="Plain text search" }%
 
+6. Configuration item set or not
+
+    %IF{ "{AntiSpam}{HideUserDetails}" then="User details are hidden" }%
+
+7. Plugin enabled test
+
+    TablePlugin is %IF{ "context TablePluginEnabled" then="enabled" else="disabled" }%.
+
+expands to: %BR% [[TablePlugin]] is enabled.
+
+8. Check access permissions
+
+    You %IF{"'%TOPIC%' allows 'change'" then="can" else="cannot"}% change this topic.
+    You %IF{"'Sandbox.TestTopic' allows 'change'" then="can" else="cannot"}% change Sandbox.TestTopic.
+    You %IF{"'Sandbox' allows 'change'" then="can" else="cannot"}% change Sandbox web
+
+expands to: %BR% You can change this topic. You can change [[TestTopic]]. You can change Sandbox web
+
+9. Check topic existance
+
+    Topic Sandbox.TestTopic %IF{"istopic 'Sandbox.TestTopic'" then="exists" else="does not exist"}%
+    Web Sandbox.TestTopic %IF{"isweb 'Sandbox'" then="exists" else="does not exist"}%
+
+expands to: %BR% Topic [[TestTopic]] exists Web [[TestTopic]] exists
+
+10. Group membership
+
+    You %IF{"'%USERNAME%' ingroup 'TWikiAdminGroup'" then="are an admin" else="are a normal user"}%
+
+expands to: %BR% You are an admin
+
 **Configuration items** are defined in [configure](http://www.dementia.org/twiki/configure). You cannot see the value of a configuration item, you can only see if the item is set or not.
 
 **Context identifiers** are used in TWiki to label various stages of the rendering process. They are especially useful for [[skin|Main/TWikiSkins]] authors to find out where they are in the rendering process. The following context identifiers are available:
@@ -161,6 +185,10 @@ examples:
     <td> in search script (see [[Main/TWikiScripts]]) </td>
   </tr>
   <tr>
+    <td> textareas_hijacked </td>
+    <td> provided for use by editors that highjack textareas, and want to signal this fact. This is used by skins, for example, so they can suppress extra controls when textareas have been hijacked. </td>
+  </tr>
+  <tr>
     <td> view </td>
     <td> in view script (see [[Main/TWikiScripts]]) </td>
   </tr>
@@ -168,8 +196,22 @@ examples:
     <td> rest </td>
     <td> in rest script (see [[Main/TWikiScripts]]) </td>
   </tr>
+  <tr>
+    <td> registration_supported </td>
+    <td> registration is supported by the current [[Main/UserMapper]]</td>
+  </tr>
+  <tr>
+    <td> registration_enabled </td>
+    <td> set if <code>{Register}{EnableNewUserRegistration}</code> is on, and registrationis supported </td>
+  </tr>
+  <tr>
+    <td> passwords_modifyable </td>
+    <td> set if the password manager support changing the password / email </td>
+  </tr>
 </table>
 
 In addition there is a context identifier for each enabled plugin; for example, if `GallousBreeksPlugin` is installed **and enabled**, then the context ID `GallousBreeksPluginEnabled` will be set. Other extensions may set additional context identifiers.
 
 The `%IF%` statement is deliberately kept simple. In particular, note that there is no way to conditionally execute a Set statement. If you need more sophisticated control over formatting, then consider using the [[SpreadSheetPlugin]].
+
+Note also that while the [[query syntax|Main/QuerySearch]] can be used to access form fields, there are some contexts in which an IF statement may be used where there is no topic context, or the topic context is not what you expected.
index 804482b..dc24ec9 100644 (file)
@@ -9,6 +9,7 @@ Use the `%INCLUDE{...}%` variable to embed the content of another topic or web p
         <li><a href="#1. Display regression test resul"> 1. Display regression test results in a TWiki page</a></li>
         <li><a href="#2. Display Google's robot.txt fi"> 2. Display Google's robot.txt file</a></li>
         <li><a href="#3. Display the current time in T"> 3. Display the current time in Tokyo in a TWiki page</a></li>
+        <li><a href="#4. Include a topic _MyTopic wit"> 4. Include a topic MyTopic with two parameters</a></li>
       </ul>
     </li>
   </ul>
@@ -16,9 +17,11 @@ Use the `%INCLUDE{...}%` variable to embed the content of another topic or web p
 
 ## <a name="Syntax Example"></a> Syntax Example
 
-`%INCLUDE{ "page" pattern="reg-exp" rev="2" warn="off" section="clients" }%`
+`%INCLUDE{ "page" pattern="reg-exp" rev="2" warn="off" section="clients" PARAMETER1="value" PARAMETER2="Some value"}%`
 
-The `pattern` parameter is optional and allows you to extract some parts of a web page. Specify a [[RegularExpression]] that scans from start (`'^'`) to end and contains the text you want to keep in parenthesis, e.g., `pattern="^.*?(from here.*?to here).*"`. You need to make sure that the integrity of a web page is not compromised; for example, if you include a table, make sure to include everything including the table end tag.
+The `pattern` parameter is optional and allows you to extract some parts of a web page. Specify a %SYSTEMWEB%.RegularExpression that scans from start (`'^'`) to end and contains the text you want to keep in parenthesis, e.g., `pattern="^.*?(from here.*?to here).*"`. You need to make sure that the integrity of a web page is not compromised; for example, if you include a table, make sure to include everything including the table end tag.
+
+The example parameters PARAMETER1 and PARAMETER2 will be defined as a variable within the scope of the included topic. The example parameters shown will result in %PARAMETER1% and %PARAMETER2% being defined within the included topic.
 
 [[VarINCLUDE]] explains the other parameters.
 
@@ -43,4 +46,18 @@ The `pattern` parameter is optional and allows you to extract some parts of a we
 - You get:
   - Tokyo:
 
+### <a name="4. Include a topic _MyTopic with"></a> 4. Include a topic MyTopic with two parameters
+
+You include the topic with this line
+
+      %INCLUDE{ "MyTopic" BETTER="apples" WORSE="Oranges"}%
+
+An example of a very simple MyTopic could contain
+
+       * I like %BETTER% better than %WORSE%.
+
+The result would be
+
+- I like apples better than oranges.
+
 **_Related Topics:_** [[VarINCLUDE]], [[UserDocumentationCategory]]
index ef7f6b0..4723dfa 100644 (file)
@@ -22,7 +22,7 @@ Administrators can enable and disable plugins using [<img src="http://www.dement
 
 Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
 
-# <a name="Plugin Diagnostics"></a> Plugin Diagnostics
+## <a name="Plugin Diagnostics"></a> Plugin Diagnostics
 
 <table border="1">
   <tr>
index b6d91ff..81530d6 100644 (file)
@@ -84,7 +84,7 @@ Icons can do a lot to enhance scannability of topics. For instance, on **HELP**
 
 **Creating image variables**
 
-You may find it easier to write shorthand graphic notation. You can create your own image variables by defining them in a preference topic (most likely [[Main.TWikiPreferences|Main/TWikiPreferences]].)
+You may find it easier to write shorthand graphic notation. You can create your own image variables by defining them in a preference topic (most likely [[%USERSWEB%.TWikiPreferences|USERSWEB/TWikiPreferences]].)
 
 A variable name may be one letter, like `Y`, or may be longer like `HELP`, `WARN` etc. You can also add your own images, e.g. a `NEW`, or a `ASK` to ask question.
 
@@ -177,7 +177,7 @@ Here are the last 15 changed pages, formatted into a neat table.
 
 When you're creating main gateway pages, you may want to temporarily (or permanently) restrict editing to yourself or a limited group of people. You can do this with a Preference setting that includes one or more users and groups. Only auhorized users will be able to use <code>**Edit**</code>.
 
-- **_Example:_** <code>**Set ALLOWTOPICCHANGE = Main.UserName, Main.GroupName**</code>
+- **_Example:_** <code>**Set ALLOWTOPICCHANGE = %USERSWEB%.UserName, %USERSWEB%.GroupName**</code>
 - %T% **To hide the setting:** Use HTML comment tags - put <code>**&lt;!--**</code> on the line \_above the setting, and <code>**--&gt;**</code> on the line below.
 
 ----
@@ -192,7 +192,7 @@ Other cusomtisations are possible using `WEBLOGOIMG`, `WEBLOGOURL`, and `WEBLOGO
 
 If you'd like to have the same customised logo for all the webs, make these changes in [[TWikiPreferences]] instead of each web's WebPreferences, e.g.,
 
-- `Set WEBLOGOIMG = %PUBURLPATH%/Main/WebPreferences/mylogo.gif`
+- `Set WEBLOGOIMG = %PUBURLPATH%/%USERSWEB%/WebPreferences/mylogo.gif`
 
 ----
 
@@ -204,7 +204,7 @@ With a simple one or two-line default topic form available for every topic - in
 
 ## <a name="Add Your Favorite _JavaScript Fe"></a> Add Your Favorite JavaScript Features
 
-You're no doubt familiar or better with HTML, JS, and "webmastering". Without getting into the [[TWikiTemplates]] system yet, you can easily edit the <code>**view.tmpl**</code> (in the `templates` directory) for some dramatic effects. The top of the template is mostly regular HTML with some variables. Open up some space in the <code>**&lt;head&gt;**</code> area, and you can drop in reliable JavaScripts - a pop-up window script, for example - or tag it as an external script.
+You're no doubt familiar or better with HTML, JS, and "webmastering". Without getting into the [[TWikiTemplates]] system yet, you can easily edit the <code>**view.pattern.tmpl**</code> (if you are using default pattern skin) (in the `templates` directory) for some dramatic effects. The top of the template is mostly regular HTML with some variables. Open up some space in the <code>**&lt;head&gt;**</code> area, and you can drop in reliable JavaScripts - a pop-up window script, for example - or tag it as an external script.
 
 - %T% Obviously, you can do the same - place a link to an external stylesheet as well. If you set values for standard HTML tags, you can control a good deal of the type size, style and color with out adding CSS tags. **_example_**
 
index a605ce0..df81c03 100644 (file)
@@ -47,8 +47,8 @@ Whenever you write <code>**ExternalSite:Page**</code> it will be linked automati
   </tr>
   <tr>
     <td> ISBN </td>
-    <td><a href="http://service.bfast.com/bfast/click?bfmid=2181&sourceid=38704253&bfpid=" target="_top">http://service.bfast.com/bfast/click?bfmid=2181&amp;sourceid=38704253&amp;bfpid=</a></td>
-    <td> Book with ISBN#$page (One click patent? Say no to Amazon!) </td>
+    <td><a href="http://www.bookfinder.com/search/?st=sr;ac=qr;isbn=" target="_top">http://www.bookfinder.com/search/?st=sr;ac=qr;isbn=</a></td>
+    <td> Book with ISBN $page </td>
   </tr>
   <tr>
     <td> News </td>
@@ -161,6 +161,16 @@ Whenever you write <code>**ExternalSite:Page**</code> it will be linked automati
     <td> '$page' on TWiki.org </td>
   </tr>
   <tr>
+    <td> TWikibug </td>
+    <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/" target="_top">http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/</a></td>
+    <td> '$page' on the TWiki issue tracking site </td>
+  </tr>
+  <tr>
+    <td> TWikirev </td>
+    <td><a href="http://develop.twiki.org/trac/changeset/" target="_top">http://develop.twiki.org/trac/changeset/</a></td>
+    <td> revision $page of TWiki svn </td>
+  </tr>
+  <tr>
     <td> UseMod </td>
     <td><a href="http://www.usemod.com/cgi-bin/wiki.pl" target="_top">http://www.usemod.com/cgi-bin/wiki.pl</a>? </td>
     <td> '$page' on 'UseMod' Wiki site </td>
index 1e74aae..64c785b 100644 (file)
@@ -91,7 +91,7 @@ Plugin settings are stored as Preferences variables. To reference a plugin setti
   </tr>
   <tr>
     <td align="right"> Copyright: </td>
-    <td> © 2006, TWiki:Main.AndreaSterbini, <a href="http://www.structuredwikis.com/" target="_top">Peter Thoeny</a></td>
+    <td> © 2001-2007, Andrea Sterbini, Peter Thoeny (<a href="http://www.twiki.net/" target="_top">TWIKI.NET</a>), [[TWiki/TWikiContributor]]</td>
   </tr>
   <tr>
     <td align="right"> License: </td>
@@ -99,13 +99,25 @@ Plugin settings are stored as Preferences variables. To reference a plugin setti
   </tr>
   <tr>
     <td align="right"> Plugin Version: </td>
-    <td> 11935 </td>
+    <td> 16052 (22 Jan 2008) </td>
   </tr>
   <tr>
     <td align="right"> Change History: </td>
     <td>  </td>
   </tr>
   <tr>
+    <td align="right"> 25 Nov 2007: </td>
+    <td> 15752 - TWikibug:Item5006 - Renamed Bugs rule to TWikibug rule (PTh) </td>
+  </tr>
+  <tr>
+    <td align="right"> 13 Aug 2007: </td>
+    <td> 14545 - TWikibug:Item4451 - Added Bugs: rule (TWiki:Main.CrawfordCurrie) </td>
+  </tr>
+  <tr>
+    <td align="right"> 11 Aug 2007: </td>
+    <td> 14538 - Fixed broken ISBN link (TWiki:Main.PeterThoeny) </td>
+  </tr>
+  <tr>
     <td align="right"> 08 Nov 2006: </td>
     <td> 11935 - Added css <code></code> (TWiki:Main.PeterThoeny) </td>
   </tr>
@@ -197,4 +209,4 @@ Plugin settings are stored as Preferences variables. To reference a plugin setti
 
 **_Related Topics:_** [[TWikiPlugins]], [[DeveloperDocumentationCategory]], [[AdminDocumentationCategory]], [[TWikiPreferences]], [[InterWikis]]
 
--- TWiki:Main.PeterThoeny - 08 Nov 2006
+-- TWiki:Main.PeterThoeny - 25 Nov 2007
index a534b61..6b111a0 100644 (file)
@@ -1,12 +1,16 @@
 # <a name="%TOPIC%"></a><a name=" %TOPIC%"></a> %TOPIC%
 
-[Mishoo JSCalendar](http://dynarch.com/mishoo/calendar.epl), packaged for use by plugins, skins and add-ons.
+![](http://www.dementia.org/twiki//view/screenshot.gif)
+
+%SHORTDESCRIPTION%
 
 <div>
   <ul>
     <li><a href="#Summary of Contents"> Summary of Contents</a></li>
     <li><a href="#Detailed Documentation"> Detailed Documentation</a><ul>
-        <li><a href="#Settings"> Settings</a></li>
+        <li><a href="#TWiki::Contrib::_JSCalendarContr"> TWiki::Contrib::JSCalendarContrib::renderDateForEdit($name, $value, $format [, \%cssClass]) -&gt; $html</a></li>
+        <li><a href="#TWiki::Contrib::_JSCalendarContr"> TWiki::Contrib::JSCalendarContrib::addHEAD($setup)</a></li>
+        <li><a href="#Using the Calendar in user forms"> Using the Calendar in user forms</a></li>
         <li><a href="#Installation Instructions"> Installation Instructions</a></li>
         <li><a href="#Contrib Info"> Contrib Info</a></li>
       </ul>
@@ -20,433 +24,96 @@ This module packages the [Mishoo JSCalendar](http://dynarch.com/mishoo/calendar.
 
 ## <a name="Detailed Documentation"></a> Detailed Documentation
 
-Read [the Mishoo documentation](http://www.dementia.org/twiki//view/doc/html/reference.html) or [visit the demo page](http://www.dementia.org/twiki//view).
+Read [the Mishoo documentation](http://www.dementia.org/twiki//view/doc/html/reference.html) or [visit the demo page](http://www.dementia.org/twiki//view) for detailed information on using the calendar widget.
+
+This package also includes a small Perl module to make using the calendar easier from TWiki plugins. This module includes the functions:
+
+### <a name="TWiki::Contrib::_JSCalendarContr"></a> TWiki::Contrib::JSCalendarContrib::renderDateForEdit($name, $value, $format [, \\%cssClass]) -&gt; $html
+
+This is the simplest way to use calendars from a plugin.
+
+- `$name` is the name of the CGI parameter for the calendar (it should be unique),
+- `$value` is the current value of the parameter (may be undef)
+- `$format` is the format to use (optional; the default is set in `configure`). The HTML returned will display a date field and a drop-down calendar.
+- `\%options` is an optional hash containing base options for the textfield.
+
+Example:
+
+    use TWiki::Contrib::JSCalendarContrib;
+    ...
+    my $fromDate = TWiki::Contrib::JSCalendarContrib::renderDateForEdit(
+       'from', '1 April 1999');
+    my $toDate = TWiki::Contrib::JSCalendarContrib::renderDateForEdit(
+       'to', undef, '%Y');
+
+### <a name="TWiki::Contrib::_JSCalendarContr"></a> TWiki::Contrib::JSCalendarContrib::addHEAD($setup)
+
+This function will automatically add the headers for the calendar to the page being rendered. It's intended for use when you want more control over the formatting of your calendars than `renderDateForEdit` affords. `$setup` is the name of the calendar setup module; it can either be omitted, in which case the method described in the Mishoo documentation can be used to create calendars, or it can be `'twiki'`, in which case a Javascript helper function called 'showCalendar' is added that simplifies using calendars to set a value in a text field. For example, say we wanted to display the date with the calendar icon _before_ the text field, using the format `%Y %b %e`
+
+    # Add styles and javascript for the calendar
+    use TWiki::Contrib::JSCalendarContrib;
+    ...
 
-This package provides a `renderFormFieldForEditHandler` that could be invoked by a plugin to ensure that forms use the [Mishoo JSCalendar](http://dynarch.com/mishoo/calendar.epl) for editing.
+    sub commonTagsHandler {
+      ....
+      # Enable 'showCalendar'
+      TWiki::Contrib::JSCalendarContrib::addHEAD( 'twiki' );
 
-This package also includes a small Perl module to make using the calendar easier from TWiki plugins. This module includes the function:
+      my $cal = CGI::image_button(
+          -name => 'img_datefield',
+          -onclick =>
+           "return showCalendar('id_datefield','%Y %b %e')",
+          -src=> TWiki::Func::getPubUrlPath() . '/' .
+                 TWiki::Func::getTwikiWebname() .
+                 '/JSCalendarContrib/img.gif',
+          -alt => 'Calendar',
+          -align => 'middle' )
+        . CGI::textfield(
+          { name => 'date', id => "id_datefield" });
+      ....
+    }
 
-    addHEAD( $setup )
+The first parameter to `showCalendar` is the id of the textfield, and the second parameter is the . See the Mishoo documentation for details of the '$e %B %Y' parameter.
 
-that can automatically add the required headers to the page being rendered. `$setup` is the name of the calendar setup module; it can either be ommitted, in which case the method described in the Mishoo documentation can be used to create calendars, or it can be `'twiki'`, in which case a helper function is added that simplifies using calendars to set a value in a text field. For example,
+`addHEAD` can be called from `commonTagsHandler` for adding the header to all pages, or from `beforeEditHandler` just for edit pages etc.
 
-        # Add styles and javascript for the calendar
-        require TWiki::Contrib::JSCalendarContrib;
-        if( $@ || !$TWiki::Contrib::JSCalendarContrib::VERSION ||
-            $TWiki::Contrib::JSCalendarContrib::VERSION < 0.961 ) {
-            TWiki::Func::writeWarning('JSCalendarContrib >=0.961 not found '.$@);
-        } else {
-            TWiki::Contrib::JSCalendarContrib::addHEAD( 'twiki' );
-        }
+### <a name="Using the Calendar in user forms"></a> Using the Calendar in user forms
 
-        $html .= CGI::textfield(
-            { name => 'datefield',
-              id => "id_datefield" });
-        $html .=
-              CGI::image_button(
-                          -name => 'datefield_calendar',
-                          -onclick =>
-                              "return showCalendar('id_datefield','%e %B %Y')",
-                          -src=> TWiki::Func::getPubUrlPath() . '/' .
-                            TWiki::Func::getTwikiWebname() .
-                                '/JSCalendarContrib/img.gif',
-                          -alt => 'Calendar',
-                          -align => 'MIDDLE' );
-                }
-            }
+You can also use the calendar directly in your own hand-built forms, without having to write any code. Just add this inline in the topic text:
 
-The first parameter to showCalendar is the id of the textfield. See the Mishoo documentation for details of the '$e %B %Y' parameter.
+    %INCLUDE{"%SYSTEMWEB%/JSCalendarContribInline"}%
 
-Note that the header will only be added once, regardless of the number of times that addHEAD is called.
+Then, to display a calendar icon next to a text input field:
 
-`addHEAD` can be called from `commonTagsHandler` for adding the header to all pages, or to `beforeEditHandler` just for edit pages etc.
+    <input type="text" id="cal_val_here" />
+    <input type="image" src="%PUBURL%/%SYSTEMWEB%/JSCalendarContrib/img.gif" onclick="javascript: return showCalendar('cal_val_here','%e %B %Y')" />
 
-### <a name="Settings"></a> Settings
+If the contrib is installed, you will see such a field here:
 
-- Name of the perl package
-  - Set STUB = TWiki::Contrib::JSCalendarContrib
-- What do I do
-  - Set SHORTDESCRIPTION = [Mishoo JSCalendar](http://dynarch.com/mishoo/calendar.epl), packaged for use by plugins, skins and add-ons.
+<input id="cal_val_here" type="text" />
+ <input onclick="javascript: return showCalendar('cal_val_here','%e %B %Y')" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/JSCalendarContrib/img.gif" type="image" />
 
 ### <a name="Installation Instructions"></a> Installation Instructions
 
-- Download the archive from the Plugins web (see below)
-- Unpack it in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0">
-  <tr>
-    <th bgcolor="#99CCCC"><strong> File: </strong></th>
-    <th bgcolor="#99CCCC"><strong> Description: </strong></th>
-  </tr>
-  <tr>
-    <td><code><b>data/TWiki/JSCalendarContrib.txt</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>lib/TWiki/Contrib/JSCalendarContrib.pm</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/twiki.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/bugtest-hidden-selects.html</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar-blue2.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar-blue.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar-brown.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar-green.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar.php</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar-setup.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar-setup_stripped.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar_stripped.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar-system.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar-tas.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar-win2k-1.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar-win2k-2.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar-win2k-cold-1.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/calendar-win2k-cold-2.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/ChangeLog</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/dayinfo.html</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/doc/html/field-button.jpg</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/doc/html/reference.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/doc/html/reference.html</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/doc/html/reference-Z-S.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/doc/reference.pdf</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/img.gif</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/index.html</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-af.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-al.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-bg.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-big5.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-big5-utf8.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-br.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ca.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-cs-utf8.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-cs-win.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-da.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-de.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-du.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-el.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-en.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-es.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-fi.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-fr.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-he-utf8.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-hr.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-hr-utf8.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-hu.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-it.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-jp.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ko.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ko-utf8.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-lt.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-lt-utf8.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-lv.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-nl.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-no.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-pl.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-pl-utf8.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-pt.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ro.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ru_win_.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ru.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-si.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-sk.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-sp.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-sv.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-tr.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-zh.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/lang/cn_utf8.js</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/active-bg.gif</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/dark-bg.gif</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/hover-bg.gif</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/menuarrow.gif</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/normal-bg.gif</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/rowhover-bg.gif</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/status-bg.gif</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/theme.css</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/title-bg.gif</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/today-bg.gif</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/transparent-bg.png</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/menuarrow.gif</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/menuarrow2.gif</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/multiple-dates.html</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/README</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/release-notes.html</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/simple-1.html</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/simple-2.html</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/simple-3.html</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/test.php</b></code></td>
-    <td>   </td>
-  </tr>
-  <tr>
-    <td><code><b>pub/TWiki/JSCalendarContrib/test-position.html</b></code></td>
-    <td>   </td>
-  </tr>
-</table>
+You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
+
+Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
+
+- If you have TWiki 4.2 or later, you can install from the `configure` interface (Go to Plugins-&gt;Find More Extensions)
+  - See the [installation supplement](http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement) on TWiki.org for more information.
+- If you have any problems, then you can still install manually from the command-line:
+  1. Download one of the `.zip` or `.tgz` archives
+  2. Unpack the archive in the root directory of your TWiki installation.
+  3. Run the installer script ( `perl <module>_installer` )
+  4. Run `configure` and enable the module, if it is a plugin.
+  5. Repeat for any missing dependencies.
+- If you are **still** having problems, then instead of running the installer script:
+  1. Make sure that the file permissions allow the webserver user to access all files.
+  2. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
+  3. Manually edit LocalSite.cfg to set any configuration variables.
+
+<div class="twikiAlert">%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your [[Main/TWikiPreferences]], if they are not already there:<br /><pre>   * Set SYSTEMWEB = %TWIKIWEB%<br />   * Set USERSWEB = %MAINWEB%</pre></div>
 
-- Make sure that all files are readable by the web server user
 - An administrator can customize the appearance of the calendar by setting the following in `LocalSite.cfg`<table border="1" cellpadding="0" cellspacing="0">
   <tr>
     <th bgcolor="#99CCCC"><strong> Setting </strong></th>
@@ -468,14 +135,16 @@ Note that the header will only be added once, regardless of the number of times
 
 ### <a name="Contrib Info"></a> Contrib Info
 
+Another great TWiki extension from the [![](http://www.dementia.org/twiki//view/wikiringlogo20x20.png) **WikiRing** ](http://wikiring.com) - working together to improve your wiki experience!
+
 <table border="1" cellpadding="0" cellspacing="0">
   <tr>
     <td align="right"> Author: </td>
-    <td> TWiki:Main/CrawfordCurrie <a href="http://www.c-dot.co.uk" target="_top">http://www.c-dot.co.uk</a></td>
+    <td> TWiki:Main/CrawfordCurrie <a href="http://c-dot.co.uk" target="_top">http://c-dot.co.uk</a></td>
   </tr>
   <tr>
     <td align="right"> Version: </td>
-    <td> 11704 of the Mishoo calendar </td>
+    <td> 16236 (22 Jan 2008) of the Mishoo calendar </td>
   </tr>
   <tr>
     <td align="right"> Copyright ©: </td>
@@ -494,31 +163,39 @@ Note that the header will only be added once, regardless of the number of times
     <td>   </td>
   </tr>
   <tr>
-    <td> 11594 </td>
+    <td align="right"> 6 Sep 2007 </td>
+    <td> Bugs:Item4030 Added doc for using the calendar in user forms </td>
+  </tr>
+  <tr>
+    <td align="right"> 13603 </td>
+    <td> Bugs:Item2982 cleaned up the interface to the contrib, re-added a date rendering function with a more generic interface </td>
+  </tr>
+  <tr>
+    <td align="right"> 11594 </td>
     <td> Allow format to be configured. </td>
   </tr>
   <tr>
-    <td> 11415 </td>
+    <td align="right"> 11415 </td>
     <td> Add a <code>renderFormFieldForEditHandler</code> so other plugins can forward to this handler to add the date field to the [[Main/TWikiForms]]. (TWiki:Main.ThomasWeigert) </td>
   </tr>
   <tr>
-    <td> 10247 </td>
-    <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item2054" rel="nofollow">Item2054</a> put the calendar at z-index 2000, way above pattern skin divs. </td>
+    <td align="right"> 10247 </td>
+    <td> Bugs:Item2054 put the calendar at z-index 2000, way above pattern skin divs. </td>
   </tr>
   <tr>
-    <td> 6634 </td>
-    <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item453" rel="nofollow">Item453</a> removed [[Main/EditTablePlugins]] private copy of the Mishoo JS calendar, and made sure it works with [[Main/JSCalendarContrib]]. Improved the documentation of the JSCalendar while I was there. </td>
+    <td align="right"> 6634 </td>
+    <td> Bugs:Item453 removed [[Main/EditTablePlugins]] private copy of the Mishoo JS calendar, and made sure it works with [[Main/JSCalendarContrib]]. Improved the documentation of the JSCalendar while I was there. </td>
   </tr>
   <tr>
-    <td> 6626 </td>
-    <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item468" rel="nofollow">Item468</a> updated docs for Dakar release </td>
+    <td align="right"> 6626 </td>
+    <td> Bugs:Item468 updated docs for Dakar release </td>
   </tr>
   <tr>
-    <td> 5048 </td>
+    <td align="right"> 5048 </td>
     <td> Cairo readiness </td>
   </tr>
   <tr>
-    <td> 5039 </td>
+    <td align="right"> 5039 </td>
     <td> Split from [[Main/SharedCode]]</td>
   </tr>
   <tr>
@@ -543,4 +220,4 @@ Note that the header will only be added once, regardless of the number of times
   </tr>
 </table>
 
-**_Related Topics:_** [[TWikiPreferences]]
+**_Related Topics:_** %SYSTEMWEB%.TWikiPreferences
diff --git a/TWiki/JSCalendarContribInline.mdwn b/TWiki/JSCalendarContribInline.mdwn
new file mode 100644 (file)
index 0000000..740c87e
--- /dev/null
@@ -0,0 +1 @@
+Inline include of [[JSCalendarContrib]] HTML for use in forms.
index e2a90c0..b2ba73f 100644 (file)
@@ -6,6 +6,6 @@ Note: this dropdown is only shown if localization is enabled.%BR% Test: <span>**
 
 Usage:
 
-    %INCLUDE{%TWIKIWEB%.LanguageSelector}%
+    %INCLUDE{%SYSTEMWEB%.LanguageSelector}%
 
 Result:
index bb0cbaf..85797b6 100644 (file)
@@ -1,63 +1,20 @@
-# <a name="%TOPIC%"></a><a name=" %TOPIC%"></a> %TOPIC%
+# <a name="Mailer Contrib"></a><a name=" Mailer Contrib"></a> Mailer Contrib
 
-Add-on to the TWiki kernel that allows users to "subscribe" to regularly scheduled e-mails containing either:
+[![](http://www.dementia.org/twiki//view/logo.gif)](http://wikiring.com)
+
+Allows users to "subscribe" to regularly scheduled e-mails containing either:
 
 - A report on changes to all topics that have changed within a particular TWiki web.
 - A report on changes to a specific topic or set of topics the user can define flexibly.
 - The entire content of a specific topic or set of topics. This is referred to as "news mode."
+- The companion plugin (TWiki:Plugins.SubscribePlugin) lets you trivially add a "Subscribe to changes" button to topics
 
-**WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please see [here](http://twiki.org/cgi-bin/view/Plugins/%TOPIC%?rev=1.17)**
+<div>WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please use <a href="http://twiki.org/cgi-bin/attach/Plugins/%TOPIC%?filename=%TOPIC%.zip&revInfo=1" target="_top">revision 17 of the zip</a>.</div>
 
 <div>
   <ul>
-    <li><a href="#tools/mailnotify"> <code>tools/mailnotify</code></a></li>
-    <li><a href="#TWiki/Contrib/_MailerContrib cod"> <code>TWiki/Contrib/MailerContrib</code> code library</a></li>
-    <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::WebNotify</a><ul>
-        <li><a href="#ClassMethod new($web, $topic)"> ClassMethod new($web, $topic)</a></li>
-        <li><a href="#ObjectMethod write_WebNotify()"> ObjectMethod writeWebNotify()</a></li>
-        <li><a href="#ObjectMethod getSubscriber($name"> ObjectMethod getSubscriber($name, $noAdd)</a></li>
-        <li><a href="#ObjectMethod getSubscribers()"> ObjectMethod getSubscribers()</a></li>
-        <li><a href="#ObjectMethod subscribe($name, $t"> ObjectMethod subscribe($name, $topics, $depth)</a></li>
-        <li><a href="#ObjectMethod unsubscribe($name,"> ObjectMethod unsubscribe($name, $topics, $depth)</a></li>
-        <li><a href="#ObjectMethod stringify() -> stri"> ObjectMethod stringify() -&gt; string</a></li>
-        <li><a href="#ObjectMethod processChange($chan"> ObjectMethod processChange($change, $db, $changeSet, $seenSet, $allSet)</a></li>
-        <li><a href="#ObjectMethod processCompulsory($"> ObjectMethod processCompulsory($topic, $db, \%allSet)</a></li>
-        <li><a href="#ObjectMethod isEmpty() -> boolea"> ObjectMethod isEmpty() -&gt; boolean</a></li>
-      </ul>
-    </li>
-    <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::Subscriber</a><ul>
-        <li><a href="#ClassMethod new($name)"> ClassMethod new($name)</a></li>
-        <li><a href="#ObjectMethod get_EmailAddresses("> ObjectMethod getEmailAddresses() -&gt; list</a></li>
-        <li><a href="#ObjectMethod subscribe($subs)"> ObjectMethod subscribe($subs)</a></li>
-        <li><a href="#ObjectMethod unsubscribe($subs)"> ObjectMethod unsubscribe($subs)</a></li>
-        <li><a href="#ObjectMethod is_SubscribedTo($to"> ObjectMethod isSubscribedTo($topic) -&gt; $subscription</a></li>
-        <li><a href="#ObjectMethod is_UnsubscribedFrom"> ObjectMethod isUnsubscribedFrom($topic) -&gt; $subscription</a></li>
-        <li><a href="#ObjectMethod stringify() -> stri"> ObjectMethod stringify() -&gt; string</a></li>
-      </ul>
-    </li>
-    <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::Subscription</a><ul>
-        <li><a href="#ClassMethod new($pages, $childDe"> ClassMethod new($pages, $childDepth, $news)</a></li>
-        <li><a href="#ObjectMethod stringify() -> stri"> ObjectMethod stringify() -&gt; string</a></li>
-        <li><a href="#ObjectMethod matches($topic, $db"> ObjectMethod matches($topic, $db, $depth) -&gt; boolean</a></li>
-        <li><a href="#ObjectMethod getMode() -> $mode"> ObjectMethod getMode() -&gt; $mode</a></li>
-      </ul>
-    </li>
-    <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::Change</a><ul>
-        <li><a href="#ClassMethod new($web)"> ClassMethod new($web)</a></li>
-        <li><a href="#ObjectMethod merge($change)"> ObjectMethod merge($change)</a></li>
-        <li><a href="#ObjectMethod expandHTML($html) -"> ObjectMethod expandHTML($html) -&gt; string</a></li>
-        <li><a href="#ObjectMethod expandPlain() -> st"> ObjectMethod expandPlain() -&gt; string</a></li>
-      </ul>
-    </li>
-    <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::UpData</a><ul>
-        <li><a href="#ClassMethod new($web)"> ClassMethod new($web)</a></li>
-        <li><a href="#ObjectMethod getParent($topic) -"> ObjectMethod getParent($topic) -&gt; string</a></li>
-      </ul>
-    </li>
-    <li><a href="#package TWiki::Contrib::Mailer"> package TWiki::Contrib::Mailer</a><ul>
-        <li><a href="#StaticMethod mailNotify($webs, $"> StaticMethod mailNotify($webs, $session, $verbose)</a></li>
-      </ul>
-    </li>
+    <li><a href="#tools/mailnotify"> tools/mailnotify</a></li>
+    <li><a href="#TWiki/Contrib/_MailerContrib cod"> TWiki/Contrib/MailerContrib code library</a></li>
     <li><a href="#Installation Instructions"> Installation Instructions</a><ul>
         <li><a href="#Setting up your cron job(s)"> Setting up your cron job(s)</a></li>
       </ul>
@@ -69,9 +26,9 @@ Add-on to the TWiki kernel that allows users to "subscribe" to regularly schedul
   </ul>
 </div>
 
-# <a name="tools/mailnotify"></a> `tools/mailnotify`
+## <a name="tools/mailnotify"></a> tools/mailnotify
 
-The central component of [[MailerContrib]] is a script, `tools/mailnotify`, that generates and sends out the emails based on analysis of
+The central component of MailerContrib is a script, `tools/mailnotify`, that generates and sends out the emails based on analysis of
 
 1. users' subcriptions listed in the WebNotify topic in each web, and
 2. changes within the respective webs.
@@ -82,26 +39,33 @@ The script collates the changes emails so that each subscriber only receives one
 
 Each web can optionally contain a topic called WebNotify.
 
-Users subscribe to email notifications using their [[WikiName]] or an alternative email address, and can specify the webs/topics they wish to track using one of these bullet list formats:
+Users subscribe to email notifications using their [[WikiName]] or an alternative email address, and can specify the webs/topics they wish to track, WWhole groups of users can also be subscribed for notification.
+
+The general format of a subscription is:
+
+_three spaces_ `*` _subscriber_ [ `:` _topics_ ]
+
+Where _subscriber_ can be a [[WikiName]], an E-mail address, or a group name. If _subscriber_ contains any characters that are not legal in an email address, then it must be enclosed in 'single' or "double" quotes.
+
+_topics_ is an optional space-separated list of topics:
 
-_three spaces_ \* [ _webname_ . ] _wikiName_ - _SMTP mail address_<br />_three spaces_ \* [ _webName_ . ] _wikiName_<br />_three spaces_ \* _SMTP mail address_<br />_three spaces_ \* _SMTP mail address_ : _topics_<br />_three spaces_ \* [ _webname_ . ] _wikiName_ : _topics_
+- ... **without** a _Web._ prefix
+- ...that exist in this web.
 
-In the above examples, _topics_ is a space-separated list of topic names. The user may further customize the specific content they will receive using the following formats:
+Users may further customize the specific content they will receive using the following controls:
 
-- Specify topics without a _Web._ prefix
-- Topics must exist in this web.
-- Topics may be specified using \* wildcards
-- Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic" (the same as not putting anything). The '-' sign means "unsubscribe" or "don't send notifications regarding this topic". This allows users to elect to filter out certain topics (and their children, to an arbitrary depth). Topic filters ('-') take precedence over topic includes ('+').
+- You can use `*` in a topic name, where it is treated as a [wildcard character](http://en.wikipedia.org/wiki/Wildcard_character). A `*` will match zero or more other characters - so, for example, `Fred*` will match all topic names starting with `Fred`, `*Fred` will match all topic names _ending_ with `Fred`, and `*` will match _all_ topic names.
+- Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic". The '-' sign means "unsubscribe" or "don't send notifications regarding this particular topic". This allows users to elect to filter out certain topics. Topic filters ('-') take precedence over topic includes ('+') i.e. if you unsubscribe from a topic it will cancel out any subscriptions to that topic.
 - Each topic may optionally be followed by an integer in parentheses, indicating the depth of the tree of children below that topic. Changes in all these children will be detected and reported along with changes to the topic itself. _Note_ This uses the TWiki "Topic parent" feature.
-- Each topic may optionally be immediately followed by an exclamation mark ! or a question mark ? with no intervening spaces, indicating that the topic (and children if there is a tree depth specifier as well) should be mailed out as **complete topics** instead of change summaries. ! causes the topic to be mailed every time even if there have been no changes, ? will mail the topic only if there have been changes to it. This only makes sense for subscriptions.
+- Each topic may optionally be immediately followed by an exclamation mark ! or a question mark ? with no intervening spaces, indicating that the topic (and children if there is a tree depth specifier as well) should be mailed out as **complete topics** instead of change summaries. ! causes the topic to be mailed every time _even if there have been no changes_, and ? will mail the topic only if there have been changes to it. This only makes sense for subscriptions, and is intended for mailshotting regular newletters.
 
 For example: Subscribe Daisy to all changes to topics in this web.
 
        * daisy.cutter@flowers.com
 
-Subscribe Daisy to all changes in all webs that start with `Web`.
+Subscribe Daisy to all changes to topics that start with `Web`.
 
-       * daisy.cutter@flowers.com: Web*
+       * daisy.cutter@flowers.com : Web*
 
 Subscribe Daisy to changes to topics starting with `Petal`, and their immediate children, WeedKillers and children to a depth of 3, and all topics that match start with `Pretty` and end with `Flowers` e.g. `PrettyPinkFlowers`
 
@@ -124,265 +88,67 @@ Subscribe GardenGroup (which includes Petunia) to all changed topics under Allne
        * GardenGroup: AllNewsLetters? (3)
        * petunia@flowers.com: - ManureNewsLetter
 
-A user may be listed many times in the WebNotify topic. Where a user has several lines in WebNotify that all match the same topic, they will only be notified about _changes_ that topic _once_ (though they will still receive individual mails for news topics).
-
-If a _TWiki group_ is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
-
-**_%T% Tip:_** List names in alphabetical order to make it easier to find the names.
-
-In the future it is intended that individual users will be able to control the frequency with which they are notified of topic changes, by changing a schedule specification in their home topic. However at present, the notification schedule is controlled by the frequency of activation of the `cron` job that runs the `mailnotify` script.
-
-%RED% **_Note_** `mailnotify` ignores permissions in webs. It is entirely possible for a user to get added to one of the subscription topics in a web, when they are not authorised to view the topics in that web. This could result in them having access to sensitive information, particularly with news mode. %ENDCOLOR%
-
-Note that when using the "news mode" ! or ? specifiers are used the entire topic text is mailed out as HTML. The `newsletter` template is used to generate the content in this mail, using whatever skin is selected in the topic being mailed.
-
-In addition, the %STARTPUBLISH% and %STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected.
-
-# <a name="TWiki/Contrib/_MailerContrib cod"></a> `TWiki/Contrib/MailerContrib` code library
-
-The second part of the module is a code library that provides the services for other applications to modify the subscription topics through a clean, well documented API. This allows (for example) plugin developers to add (for example) a "Register me for this newsletter" button to their pages. The main interface is the `WebNotify` package described below.
-
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::WebNotify
-
-Object that represents the contents of a [[WebNotify]] topic in a TWiki web
-
-## <a name="ClassMethod new($web, $topic)"></a> [[ClassMethod]] new($web, $topic)
-
-Create a new object by parsing the content of the given topic in the given web. This is the normal way to load a [[WebNotify]] topic. If the topic does not exist, it will create an empty object.
-
-## <a name="ObjectMethod write_WebNotify()"></a> [[ObjectMethod]] writeWebNotify()
-
-Write the object to the [[WebNotify]] topic it was read from. If there is a problem writing the topic (e.g. it is locked), the method will return an error message. If everything is ok it will return undef.
-
-## <a name="ObjectMethod getSubscriber($name"></a> [[ObjectMethod]] getSubscriber($name, $noAdd)
-
-- `$name` - Name of subscriber (wikiname with no web or email address)
-- `$noAdd` - If false or undef, a new subscriber will be created for this name
-
-Get a subscriber from the list of subscribers, and return a reference to the Subscriber object. If $noAdd is true, and the subscriber is not found, undef will be returned. Otherwise a new Subscriber object will be added if necessary.
-
-## <a name="ObjectMethod getSubscribers()"></a> [[ObjectMethod]] getSubscribers()
-
-Get a list of all subscriber names (unsorted)
-
-## <a name="ObjectMethod subscribe($name, $t"></a> [[ObjectMethod]] subscribe($name, $topics, $depth)
-
-- `$name` - Name of subscriber (wikiname with no web or email address)
-- `$topics` - wildcard expression giving topics to subscribe to
-- `$depth` - Child depth to scan (default 0)
-- `$mode` - ! if this is a non-changes subscription and the topics should be mailed evebn if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.
-
-Add a subscription, adding the subscriber if necessary.
-
-## <a name="ObjectMethod unsubscribe($name,"></a><a name="ObjectMethod unsubscribe($name, "></a> [[ObjectMethod]] unsubscribe($name, $topics, $depth)
-
-- `$name` - Name of subscriber (wikiname with no web or email address)
-- `$topics` - wildcard expression giving topics to subscribe to
-- `$depth` - Child depth to scan (default 0)
-
-Add an unsubscription, adding the subscriber if necessary. An unsubscription is a specific request to ignore notifications for a topic for this particular subscriber.
-
-## <a name="ObjectMethod stringify() - strin"></a> [[ObjectMethod]] stringify() -&gt; string
-
-Return a string representation of this object, in [[WebNotify]] format.
-
-## <a name="ObjectMethod processChange($chan"></a> [[ObjectMethod]] processChange($change, $db, $changeSet, $seenSet, $allSet)
-
-- `$change` - ref of a TWiki::Contrib::Mailer::Change
-- `$db` - TWiki::Contrib::MailerContrib::UpData database of parent references
-- `$changeSet` - ref of a hash mapping emails to sets of changes
-- `$seenSet` - ref of a hash recording indices of topics already seen
-- `$allSet` - ref of a hash that maps topics to email addresses for news subscriptions
-
-Find all subscribers that are interested in the given change. Only the most recent change to each topic listed in the .changes file is retained. This method does _not_ change this object.
-
-## <a name="ObjectMethod processCompulsory($"></a> [[ObjectMethod]] processCompulsory($topic, $db, \\%allSet)
-
-- `$topic` - topic name
-- `$db` - TWiki::Contrib::MailerContrib::UpData database of parent references
-- `\%allSet` - ref of a hash that maps topics to email addresses for news subscriptions
-
-## <a name="ObjectMethod isEmpty() - boolean"></a> [[ObjectMethod]] isEmpty() -&gt; boolean
-
-Return true if there are no subscribers
-
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::Subscriber
-
-Object that represents a subscriber to notification. A subscriber is a name (which may be a wikiName or an email address) and a list of subscriptions which describe the topis subscribed to, and unsubscriptions representing topics they are specifically not interested in. The subscriber name may also be a group, so it may expand to many email addresses.
-
-## <a name="ClassMethod new($name)"></a> [[ClassMethod]] new($name)
-
-- `$name` - Wikiname, with no web, or email address, of user targeted for notification
-
-Create a new user.
-
-## <a name="ObjectMethod get_EmailAddresses("></a> [[ObjectMethod]] getEmailAddresses() -&gt; list
-
-Get a list of email addresses for the user(s) represented by this subscription
-
-## <a name="ObjectMethod subscribe($subs)"></a> [[ObjectMethod]] subscribe($subs)
-
-- `$subs` - Subscription object
-
-Add a new subscription to this subscriber object. The subscription will always be added, even if there is a wildcard overlap with an existing subscription.
-
-## <a name="ObjectMethod unsubscribe($subs)"></a> [[ObjectMethod]] unsubscribe($subs)
+Subscribe `IT:admins` (a non-TWiki group defined by an alternate user mapping) to all changes to Web\* topics.
 
-- `$subs` - Subscription object
+       * 'IT:admins' : Web*
 
-Add a new unsubscription to this subscriber object. The unsubscription will always be added, even if there is a wildcard overlap with an existing subscription or unsubscription.
-
-An unsubscription is a statement of the subscribers desire _not_ to be notified of changes to this topic.
-
-## <a name="ObjectMethod is_SubscribedTo($to"></a> [[ObjectMethod]] isSubscribedTo($topic) -&gt; $subscription
-
-- `$topic` - Topic object we are checking
-- `$db` - TWiki::Contrib::MailerContrib::UpData database of parents
-
-Check if we have a subscription to the given topic. Return the subscription that matches if we do, undef otherwise.
-
-## <a name="ObjectMethod is_UnsubscribedFrom"></a> [[ObjectMethod]] isUnsubscribedFrom($topic) -&gt; $subscription
-
-- `$topic` - Topic object we are checking
-- `$db` - TWiki::Contrib::MailerContrib::UpData database of parents
-
-Check if we have an unsubscription from the given topic. Return the subscription that matches if we do, undef otherwise.
-
-## <a name="ObjectMethod stringify() - strin"></a> [[ObjectMethod]] stringify() -&gt; string
-
-Return a string representation of this object, in WebNotify format.
-
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::Subscription
-
-Object that represents a single subscription of a user to notification on a page. A subscription is expressed as a page spec (which may contain wildcards) and a depth of children of matching pages that the user is subscribed to.
-
-## <a name="ClassMethod new($pages, $childDe"></a> [[ClassMethod]] new($pages, $childDepth, $news)
-
-- `$pages` - Wildcarded expression matching subscribed pages
-- `$childDepth` - Depth of children of $topic to notify changes for. Defaults to 0
-- `$mode` - ! if this is a non-changes subscription and the topics should be mailed evebn if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.
-
-Create a new subscription.
-
-## <a name="ObjectMethod stringify() - strin"></a> [[ObjectMethod]] stringify() -&gt; string
-
-Return a string representation of this object, in WebNotify format.
-
-## <a name="ObjectMethod matches($topic, $db"></a> [[ObjectMethod]] matches($topic, $db, $depth) -&gt; boolean
-
-- `$topic` - Topic object we are checking
-- `$db` - TWiki::Contrib::MailerContrib::UpData database of parent names
-- `$depth` - If non-zero, check if the parent of the given topic matches as well. undef = 0.
-
-Check if we match this topic. Recurses up the parenthood tree seeing if this is a child of a parent that matches within the depth range.
-
-## <a name="ObjectMethod getMode() - $mode"></a> [[ObjectMethod]] getMode() -&gt; $mode
-
-Return ! if this is a non-changes subscription and the topics should be mailed even if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.
-
-----
-
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::Change
-
-Object that represents a change to a topic.
-
-## <a name="ClassMethod new($web)"></a> [[ClassMethod]] new($web)
-
-- `$web` - Web name
-- `$topic` - Topic name
-- `$author` - String author of change
-- `$time` - String time of change
-- `$rev` - Revision identifier
-
-Construct a new change object.
-
-## <a name="ObjectMethod merge($change)"></a> [[ObjectMethod]] merge($change)
-
-- `$change` - Change record to merge
-
-Merge another change record with this one, so that the combined record is a reflection of both changes.
-
-## <a name="ObjectMethod expandHTML($html) -"></a> [[ObjectMethod]] expandHTML($html) -&gt; string
-
-- `$html` - Template to expand keys within
-
-Expand an HTML template using the values in this change. The following keys are expanded: %TOPICNAME%, %AUTHOR%, %TIME%, %REVISION%, %TEXTHEAD%.
-
-Returns the expanded template.
-
-## <a name="ObjectMethod expandPlain() - str"></a> [[ObjectMethod]] expandPlain() -&gt; string
+A user may be listed many times in the WebNotify topic. Where a user has several lines in WebNotify that all match the same topic, they will only be notified about _changes_ that topic _once_ (though they will still receive individual mails for news topics).
 
-Generate a plaintext version of this change.
+If a _group_ is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
 
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::UpData
+\_\_%X% Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for email addresses. A user identified by an email address will only be sent change notifications if the topic they are asubscribed to is readable by guest users. You can limit what email addresses can be used in WebNotify, or even block use of emails altogther, using the `{MailerContrib}{EmailFilterIn} setting in =configure`.
 
-Object that lazy-scans topics to extract parent relationships.
+**_%T% Tip:_** List names in alphabetical order to make it easier to find the names.
 
-## <a name="ClassMethod new($web)"></a> [[ClassMethod]] new($web)
+In the future it is intended that individual users will be able to control the frequency with which they are notified of topic changes, by changing a schedule specification in their home topic. However at present, the notification schedule is controlled by the frequency of activation of the `cron` job that runs the `mailnotify` script.
 
-- `$web` - Web we are building parent relationships for
+Note that when using the "news mode" `!` or `?` specifiers the entire topic text is mailed out as HTML. The `newsletter` template is used to generate the content in this mail, using whatever skin is selected in the topic being mailed.
 
-Constructor for a web; initially empty, will lazy-load as topics are referenced.
+In addition, the %STARTPUBLISH% and %STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected in news mode.
 
-## <a name="ObjectMethod getParent($topic) -"></a> [[ObjectMethod]] getParent($topic) -&gt; string
+## <a name="TWiki/Contrib/_MailerContrib cod"></a> TWiki/Contrib/MailerContrib code library
 
-Get the name of the parent topic of the given topic
+The second part of the module is a code library that provides the services for other applications to modify the subscription topics through a clean, well documented API. This allows (for example) plugin developers to add (for example) a "Register me for this newsletter" button to their pages. Developers should refer to the POD documentation for the WebNotify class as their starting point.
 
-# <a name="package TWiki::Contrib::Mailer"></a> package TWiki::Contrib::Mailer
+## <a name="Installation Instructions"></a> Installation Instructions
 
-Package of support for extended WebNotify notification, supporting per-topic notification and notification of changes to children.
+You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
 
-Also supported is a simple API that can be used to change the WebNotify topic from other code.
+Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
 
-## <a name="StaticMethod mailNotify($webs, $"></a> [[StaticMethod]] mailNotify($webs, $session, $verbose)
+- If you have TWiki 4.2 or later, you can install from the `configure` interface (Go to Plugins-&gt;Find More Extensions)
+  - See the [installation supplement](http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement) on TWiki.org for more information.
+- If you have any problems, then you can still install manually from the command-line:
+  1. Download one of the `.zip` or `.tgz` archives
+  2. Unpack the archive in the root directory of your TWiki installation.
+  3. Run the installer script ( `perl <module>_installer` )
+  4. Run `configure` and enable the module, if it is a plugin.
+  5. Repeat for any missing dependencies.
+- If you are **still** having problems, then instead of running the installer script:
+  1. Make sure that the file permissions allow the webserver user to access all files.
+  2. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
+  3. Manually edit LocalSite.cfg to set any configuration variables.
 
-- `$webs` - filter list of names webs to process. Wildcards (\*) may be used.
-- `$session` - optional session object. If not given, will use a local object.
-- `$verbose` - true to get verbose (debug) output
+<div class="twikiAlert">%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your [[Main/TWikiPreferences]], if they are not already there:<br /><pre>   * Set SYSTEMWEB = %TWIKIWEB%<br />   * Set USERSWEB = %MAINWEB%</pre></div>
 
-Main entry point.
+- To make sure the installation was successful, run the `mailnotify` script from the command line, with no parameters. In this case it will print out what it would have done to `STDOUT`.
 
-Process the WebNotify topics in each web and generate and issue notification mails. Designed to be invoked from the command line; should only be called by `mailnotify` scripts.
+**Additional settings**
 
-# <a name="Installation Instructions"></a> Installation Instructions
+- You can change the regular expression that matches email addresses in WebNotify using the `{MailerContrib}{EmailFilterIn} setting in =configure`. This allows you to limit the domains to which emails can be sent, or even block email addresses altogether.
 
-You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
+### <a name="Setting up your cron job(s)"></a> Setting up your cron job(s)
 
-Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
+You need to set up a `cron` (or equivalent) job to run the `tools/mailnotify` perl script.
 
-- If you have TWiki 4.1 or later, and Perl 5.8, you can install from the `configure` interface (Go to Plugins-&gt;Find More Extensions)
-  - The webserver user has to have permission to write to all areas of your installation for this to work.
-- If you have a permanent connection to the internet (and Perl 5.8), you are recommended to use the automatic installer script
-  - Just download the `MailerContrib_installer` perl script and run it.
-- **Notes:**
-  - The installer script will:
-    - Automatically resolve dependencies,
-    - Copy files into the right places in your local install (even if you have renamed data directories),
-    - check in new versions of any installed files that have existing RCS histories files in your existing install (such as topics).
-    - If the $TWIKI\_PACKAGES environment variable is set to point to a directory, the installer will try to get archives from there. Otherwise it will try to download from twiki.org or cpan.org, as appropriate.
-    - (Developers only: the script will look for twikiplugins/MailerContrib/MailerContrib.tgz before downloading from TWiki.org)
-  - If you don't have a permanent connection, you can still use the automatic installer, by downloading all required TWiki archives to a local directory.
-    - Point the environment variable `$TWIKI_PACKAGES` to this directory, and the installer script will look there first for required TWiki packages.
-      - `$TWIKI_PACKAGES` is actually a path; you can list several directories separated by :
-    - If you are behind a firewall that blocks access to CPAN, you can build a local CPAN mini-mirror, as described at [http://twiki.org/cgi-bin/view/Codev/BuildingDakar#CPAN\_local\_minimirror](http://twiki.org/cgi-bin/view/Codev/BuildingDakar#CPAN_local_minimirror)
-- If you don't want to use the installer script, or have problems on your platform (e.g. you don't have Perl 5.8), then you can still install manually:
-  1. Download and unpack one of the `.zip` or `.tgz` archives to a temporary directory.
-  2. Manually copy the contents across to the relevant places in your TWiki installation.
-  3. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
-  4. Manually edit LocalSite.cfg to set any configuration variables.
-  5. Run `configure` and enable the module, if it is a plugin.
-  6. Repeat from step 1 for any missing dependencies.
-
-- To make sure the installation was successful, run the `mailnotify` script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
-
-## <a name="Setting up your cron job(s)"></a> Setting up your cron job(s)
-
-You need to set up a `cron` (or equivalent) job to run `tools/mailnotify`.
-
-Usage: <code>perl -I &lt;bin&gt; mailnotify [-q] [-news] [ _web1 web2 ... webN_ ]</code> &lt;bin&gt; is the path to the TWiki bin directory, so that the script can find the rest of TWiki.
+The script is used as follows: <code>perl -I _bin_ mailnotify [-q] [-news] [ _web1 web2 ... webN_ ]</code>
 
 <table border="1" cellpadding="0" cellspacing="0">
   <tr>
+    <td><em>bin</em></td>
+    <td> path to the TWiki bin directory, so that the script can find the rest of TWiki. </td>
+  </tr>
+  <tr>
     <td><code>-q</code></td>
     <td> Don't print progress information </td>
   </tr>
@@ -392,7 +158,7 @@ Usage: <code>perl -I &lt;bin&gt; mailnotify [-q] [-news] [ _web1 web2 ... webN_
   </tr>
   <tr>
     <td><code><i>web1 web2 ... webN</i></code></td>
-    <td> List of webs to process, separated by spaces or commas. Default is to process all legal TWiki webs. Wildcards (*) are supported. </td>
+    <td> List of webs to process, separated by spaces or commas. The default is to process all webs. Wildcards (*) are supported. </td>
   </tr>
 </table>
 
@@ -400,13 +166,17 @@ For example, assuming TWiki was installed at `/usr/local/twiki`, this cron entry
 
     0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q Public Private
 
-will generate change notifications for the `Public` and `Private` webs every night at midnight.
+will generate change notifications for the `Public` and `Private` webs every night at midnight. (Google for `crontab` for more information on what all the `0 0 * * *` fields mean)
+
+    0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q -Sandbox
+
+will generate change notifications for all webs, except the `Sandbox` web.
 
     0 0 * * 0 cd /usr/local/twiki && perl -I bin tools/mailnotify -news
 
 will generate newsletters from **all** webs every week on midnight Saturday.
 
-# <a name="Developer Notes"></a> Developer Notes
+## <a name="Developer Notes"></a> Developer Notes
 
 The changes mails sent to users are based on a TWiki template called `mailnotify`. This template must contain the following definitions.
 
@@ -445,7 +215,14 @@ The default template sends multipart mails containing both HTML and plaintext ve
 
 Newsletters are sent after formatting using the standard `view` template, using whatever skin is selected in the topic being mailed.
 
-## <a name="Contrib Info"></a> Contrib Info
+### <a name="Contrib Info"></a> Contrib Info
+
+Another great TWiki extension from the [![](http://www.dementia.org/twiki//view/wikiring.png) **WikiRing** ](http://wikiring.com) - working together to improve your wiki experience!
+
+Many thanks to the following sponsors for supporting this work:
+
+- [Wind River](http://www.windriver.com)
+- [WikiGardens](http://wikigardens.com)
 
 <table border="1" cellpadding="0" cellspacing="0">
   <tr>
@@ -461,10 +238,42 @@ Newsletters are sent after formatting using the standard `view` template, using
     <td> GPL </td>
   </tr>
   <tr>
+    <td align="right"> Version: </td>
+    <td> 16078 (22 Jan 2008) </td>
+  </tr>
+  <tr>
     <td align="right"> Change History: </td>
     <td>   </td>
   </tr>
   <tr>
+    <td align="right"> 2 Nov 2007 </td>
+    <td> Bugs:Item4818: added quotes to support non-alphabetic and other wierd group names Bugs:Item4887: corrected minor rendering error Bugs:Item4917: removed dependence on symbolic web names </td>
+  </tr>
+  <tr>
+    <td align="right"> 9 Sep 2007 </td>
+    <td> Bugs:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users. </td>
+  </tr>
+  <tr>
+    <td align="right"> 6 Sep 2007 </td>
+    <td> Bugs:Item4488 doc tweaks </td>
+  </tr>
+  <tr>
+    <td align="right"> 14550 </td>
+    <td> Bugs:Item4461 - 'Changed' link now points to most recent changes, not the entire history </td>
+  </tr>
+  <tr>
+    <td align="right"> 22 Jun 2007 </td>
+    <td> Bugs:Item4284 - added access control checks and email filter </td>
+  </tr>
+  <tr>
+    <td align="right"> 21 May 2007 </td>
+    <td> Bugs:Item3969 - 8bit email fix (TWiki:Main.WillNorris) </td>
+  </tr>
+  <tr>
+    <td align="right"> 13623 </td>
+    <td> Bugs:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down. </td>
+  </tr>
+  <tr>
     <td align="right"> 12496 </td>
     <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item3415" rel="nofollow">Item3415</a> mailnotify did not send notifications to intranet users because of wrong call to findUser. </td>
   </tr>
index fbf5b56..85f7c8e 100644 (file)
@@ -4,7 +4,7 @@
 - **Edit link:** To edit a page, simply click on the <code>**Edit**</code> link at the top or bottom of the page.
 - **Auto links:** Web pages are [[linked automatically|Main/WikiWord]]. You do not need to learn HTML commands to link pages.
 - **Text formatting:** Simple, powerful and easy-to-learn [[text formatting rules|Main/WikiSyntax]]. Basically you write text like you would write an e-mail.
-- **Webs:** Pages are grouped into [[TWiki webs|TWiki/SiteMap]] (or collections). This allows you to set up separate collaboration groups.
+- **Webs:** Pages are grouped into [[TWiki webs|SYSTEMWEB/SiteMap]] (or collections). This allows you to set up separate collaboration groups.
 - **Search:** [[Full text search|Main/WebSearch]] with/without regular expressions. See a sample [search result](http://www.dementia.org/twiki/search/TWiki/?scope=text&search=learn).
 - **E-mail notification:** Get [[automatically notified|Main/WebChangesAlert]] when something has changed in a TWiki web.
 - **Structured content:** Use [[TWikiForms]] to classify and categorize unstructured web pages and to create simple workflow systems.
index c0fafb3..961b477 100644 (file)
@@ -1,3 +1,7 @@
+# <a name="Managing Topics"></a> Managing Topics
+
+_Browser-based rename, move, and delete for individual topics_
+
 <div>
   <ul>
     <li><a href="#Managing Topics"> Managing Topics</a><ul>
   </ul>
 </div>
 
-# <a name="Managing Topics"></a> Managing Topics
-
-_Browser-based rename, move, and delete for individual topics_
-
 ## <a name="Overview"></a> Overview
 
 You can use browser-based controls to change a topic's name, move it to another TWiki web, or delete it to a hidden `Trash` web.
@@ -48,7 +48,7 @@ The `Trash` web should be be cleared periodically, by archiving (saving) the tex
 
 ## <a name="Redirecting from an Old Topic"></a> Redirecting from an Old Topic
 
-You can use [[TWikiMetaData]] to place a command in the [[WebTopicViewTemplate]] and [[WebTopicNonWikiTemplate]] that will indicate that a topic has been moved by searching for the tag %META:TOPICMOVED\{...\}%. Customize something like this:
+You can use [[TWikiMetaData]] to place a command in the %SYSTEMWEB%.WebTopicViewTemplate and %SYSTEMWEB%.WebTopicNonWikiTemplate that will indicate that a topic has been moved by searching for the tag %META:TOPICMOVED\{...\}%. Customize something like this:
 
 > %<nop>METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%"
 >     title="This topic used to exist and was moved to: "}%
@@ -70,7 +70,7 @@ Changed references are kept are as short as possible, ex: `topic` is used in pre
 
 ### <a name="Effect of User Access Settings"></a> Effect of User Access Settings
 
-User permissions affect the Rename function in various ways. To rename a topic, you need both <code>**ALLOWTOPICVIEW**</code> and <code>**ALLOWTOPICCHANGE**</code> permission for that topic. To alter referring topics, you need change permission. See [[TWikiAccessControl]] for information on setting up access permissions.
+User permissions affect the 'rename' functions in various ways. To rename a topic, you need all of <code>**VIEW**</code>, <code>**CHANGE**</code> and <code>**RENAME**</code> access to that topic. To alter referring topics, you need <code>**CHANGE**</code> access. See [[TWikiAccessControl]] for information on setting up access permissions.
 
 ## <a name="Special Considerations"></a> Special Considerations
 
index 4116fb1..3a47a31 100644 (file)
@@ -1,3 +1,7 @@
+# <a name="Manage Users"></a> Manage Users
+
+_Register users on your TWiki site; change/reset/install passwords; remove user accounts_
+
 <div>
   <ul>
     <li><a href="#Manage Users"> Manage Users</a><ul>
   </ul>
 </div>
 
-# <a name="Manage Users"></a> Manage Users
-
-_Register users on your TWiki site; change/reset/install passwords; remove user accounts_
+%X% Some of the features below may be disabled, depending on your TWiki configuration.
 
 ## <a name="Authentication and Access Contro"></a> Authentication and Access Control
 
-- [[TWikiUserAuthentication]] describes options of user authentication
+- [[TWikiUserAuthentication]] describes your options for user authentication
 - [[TWikiAccessControl]] describes how to define groups and how to restrict access to content
 
 ## <a name="Register User"></a> Register User
 
-It is not necessary to have user home pages in the TWiki system for Authentication to work - see [[TWikiUserAuthentication]] for details.
+You don't have to have user home pages in TWiki for Authentication to work - see [[TWikiUserAuthentication]] for details.
 
-- [[TWikiRegistration]] is for users to fill out a form
-- [[NewUserTemplate]] can be changed to customize user home pages, it can optionally use the [[UserForm]] to define user fields as meta data
-- [[BulkRegistration]] is for administrators to use to set up one or more accounts: either from a table or from an external file
+- [[TWikiRegistration]] is used when you want new users to individually register with TWiki by filling out a form
+- You can create a custom versions of [[NewUserTemplate]] and [[UserForm]]
+- [[BulkRegistration]] is used by administrators to register multiple users at the same time
 
 ## <a name="Change, Reset and Install Passwo"></a> Change, Reset and Install Passwords
 
-- [[ChangePassword]] is for users who can remember their password and want to change it
-- [[ResetPassword]] is for users who cannot remember their password; a system generated password is e-mailed to them
+_Note that the below features are only relevant when you use an internal password manager where TWiki can set and reset passwords._
+
+- [[ChangePassword]] is for users who _can_ remember their password and want to change it
+- [[ResetPassword]] is for users who _cannot_ remember their password; a system generated password is e-mailed to them
 - [[BulkResetPassword]] if for administrators who want to reset many passwords at once
+- [[ChangeEmailAddress]] changes the hidden email address stored in the password file
 
 ## <a name="Changing User Account Names"></a> Changing User Account Names
 
@@ -46,8 +51,8 @@ To change the user's [[WikiName]]:
 
 If external authentication is used and you want to change the login name:
 
-- The login name needs to be changed in the directory server, such as AD or LDAP
-- In TWiki's [[Main.TWikiUsers|Main/TWikiUsers]] topic, fix the mapping from login name to [[WikiName]] such as from:%BR% `   * JohnSmith - john - 13 Sep 2006` %BR% to: %BR% `   * JohnSmith - jsmith - 13 Sep 2006`
+- The login name needs to be changed in the authentication server (e.g. Active Directory)
+- In TWiki's [[Main.TWikiUsers|Main/TWikiUsers]] topic, fix the mapping from login name to [[WikiName]]:%BR% `   * JaneSmith - jsmith - 13 Sep 2006` %BR% to: %BR% `   * JaneMiller - jmiller - 13 Sep 2006`
 
 ## <a name="Removing User Accounts"></a> Removing User Accounts
 
@@ -59,6 +64,6 @@ To remove a user account (FredQuimby, who logs in as "fred"):
 3. Remove `FredQuimby` from all groups and from all the `ALLOWWEB/ALLOWTOPIC...` declarations, if any.%BR% **_Note:_** If you fail to do this you risk creating a security hole, as the next user to register with the wikiname FredQuimby will inherit the old FredQuimby's permissions.
 4. _[optional]_ Delete their user topic Main.FredQuimby (including attachments, if any.)
 
-**_Note:_** Consider leaving the user topic file in place so their past signatures and revision author entries don't end up looking like [[AnUncreatedTopic]]. If you want to make it clear the user is no longer with the organization or has been banished, replace the topic content with a note to that effect. The existance of the UserName topic should also prevent that user name from being re-used, sealing the potential security hole regarding inherited permissions..
+**_Note:_** Consider leaving the user topic file in place so their past signatures and revision author entries don't end up looking like [[AnUncreatedTopic]]. If you want to make it clear the user is no longer around, replace the topic content with a note to that effect. The existance of the UserName topic should also prevent that user name from being re-used, sealing the potential security hole regarding inherited permissions..
 
 **_Related Topics:_** [[AdminDocumentationCategory]]
index 3695683..39df44e 100644 (file)
@@ -1,32 +1,32 @@
+# <a name="Managing Webs"></a> Managing Webs
+
+_Adding, renaming and deleting webs are all web-based operations._
+
 <div>
   <ul>
     <li><a href="#Managing Webs"> Managing Webs</a><ul>
         <li><a href="#Overview"> Overview</a></li>
         <li><a href="#Choose Web Template"> Choose Web Template</a></li>
         <li><a href="#Adding a New Web"> Adding a New Web</a></li>
+        <li><a href="#Hierarchical Webs"> Hierarchical Webs</a><ul>
+            <li><a href="#Subweb Preferences are Inherited"> Subweb Preferences are Inherited</a></li>
+            <li><a href="#Navigation"> Navigation</a></li>
+          </ul>
+        </li>
         <li><a href="#Renaming or Deleting a Web"> Renaming or Deleting a Web</a><ul>
             <li><a href="#Permissions"> Permissions</a></li>
             <li><a href="#Edit Conflicts"> Edit Conflicts</a></li>
             <li><a href="#Renaming the webs in the distrib"> Renaming the webs in the distribution</a></li>
           </ul>
         </li>
-        <li><a href="#Hierarchical Webs"> Hierarchical Webs</a><ul>
-            <li><a href="#Subweb Preferences are Inherited"> Subweb Preferences are Inherited</a></li>
-            <li><a href="#Navigation"> Navigation</a></li>
-          </ul>
-        </li>
       </ul>
     </li>
   </ul>
 </div>
 
-# <a name="Managing Webs"></a> Managing Webs
-
-_Adding, renaming and deleting webs are all web-based operations._
-
 ## <a name="Overview"></a> Overview
 
-A [[TWikiSite]] is divided into webs; each one represents one subject, one area of collaboration. Administrators (in the [[TWikiAdminGroup]]) can add/rename/delete webs.
+A [[TWikiSite]] is divided into webs; each one represents one subject, one area of collaboration. Administrators can add/rename/delete webs.
 
 <a name="WebTemplate"></a>
 
@@ -36,13 +36,13 @@ There are two methods used to create a new web. First you can use a specially de
 
 The second method is to use an existing web as a template web. This may be useful if you already have a web that you would like to use as a starting point. Only topics that have names beginning with **Web...** (like "WebHome", "WebNotify", etc.) are copied.
 
-In either case you will want to be sure to verify that your new web has all the custom modifications that you desire.
+In either case you will want to be sure to verify that your new web has all the custom modifications that you desire. Any [[TWikiVariables]] defined in the form below will automatically be set in the WebPreferences of the new web.
 
 <a name="CreateNewWeb"></a>
 
 ## <a name="Adding a New Web"></a> Adding a New Web
 
-<form action="http://www.dementia.org/twiki/manage/%WEB%/%TOPIC%" method="post" name="admin"> Create a new web by filling out this form.%BR% <strong><em>%X% Note:</em></strong> <strong>Keep the number of webs to a minimum!</strong> It is not recommended to create a new web for each little project. You can organize content within a web using categories, [[Main/TWikiForms]] and [[Main/FormattedSearch]]. Cross-linking topics and search is easier if there are only a few larger webs. <table border="1" cellpadding="0" cellspacing="0">
+<form action="http://www.dementia.org/twiki/manage/%WEB%/%TOPIC%" method="post" name="admin"> Create a new web by filling out this form.%BR% <strong><em>%X% Note:</em></strong> <strong>Keep the number of webs to a minimum!</strong> Don't create a new web for each little project. Cross-linking topics is easier, and searches are faster, if there are only a few larger webs. <table border="1" cellpadding="0" cellspacing="0">
     <tr>
       <th align="right" bgcolor="#99CCCC"><strong> Name of new web: </strong></th>
       <td><input name="newweb" size="16" type="text" value="" /></td>
@@ -55,20 +55,25 @@ In either case you will want to be sure to verify that your new web has all the
     </tr>
     <tr>
       <th align="right" bgcolor="#99CCCC"><strong> Web color: </strong></th>
-      <td><input name="webbgcolor" size="16" type="text" value="#D0D0D0" /></td>
+      <td><input name="WEBBGCOLOR" size="16" type="text" value="#D0D0D0" /></td>
       <td> Enter a [[Main/StandardColors]] code for the web </td>
     </tr>
     <tr>
+      <th align="right" bgcolor="#99CCCC"><strong> Site Map: </strong></th>
+      <td><input checked name="SITEMAPLIST" type="radio" value="on" /> Yes   <input name="SITEMAPLIST" type="radio" value="" /> No </td>
+      <td> Include this web in the site map </td>
+    </tr>
+    <tr>
       <th align="right" bgcolor="#99CCCC"><strong> Description:<br />  <br />   </strong></th>
-      <td colspan="2"><input name="sitemapwhat" size="60" type="text" value="" /><br /> Enter a short description of the web. Write <code>Web.TopicName</code> instead of just <code>TopicName</code> if you include links. This will list the web in the [[TWiki/SiteMap]] (leave field empty if you prefer not to update the directory.) </td>
+      <td colspan="2"><input name="SITEMAPWHAT" size="60" type="text" value="" /><br /> Enter a short description of the web. Write <code>Web.TopicName</code> instead of just <code>TopicName</code> if you include links. This description will be used in the %SYSTEMWEB%.SiteMap </td>
     </tr>
     <tr>
       <th align="right" bgcolor="#99CCCC"><strong> Use to...<br />   </strong></th>
-      <td colspan="2"><input name="sitemapuseto" size="60" type="text" value="...collaborate on" /><br /> Continue the sentence describing the intended use. This is also for the [[TWiki/SiteMap]]</td>
+      <td colspan="2"><input name="SITEMAPUSETO" size="60" type="text" value="...collaborate on" /><br /> Continue the sentence describing the intended use. This is also for the %SYSTEMWEB%.SiteMap </td>
     </tr>
     <tr>
-      <th align="right" bgcolor="#99CCCC"><strong> Set NOSEARCHALL: </strong></th>
-      <td><input checked name="nosearchall" type="radio" value="" /> No   <input name="nosearchall" type="radio" value="on" /> Yes </td>
+      <th align="right" bgcolor="#99CCCC"><strong> Hidden: </strong></th>
+      <td><input name="NOSEARCHALL" type="radio" value="on" /> Yes   <input checked name="NOSEARCHALL" type="radio" value="" /> No </td>
       <td> Specify if you want to exclude the web from a "search all webs" search. <strong>This will not prevent users accessing the web</strong>. It will simply hide it from searches. </td>
     </tr>
     <tr>
@@ -79,34 +84,12 @@ In either case you will want to be sure to verify that your new web has all the
 
 **_Notes:_**
 
-- You have to have `ROOTCHANGE` access to create a top-level web (one with no parent)
-- Attachments will NOT get copied over along with their topics
-- While creating the new web, TWiki will update the following variables in the [[WebPreferences]]: `WEBBGCOLOR`, `SITEMAPLIST`, `SITEMAPWHAT`, `SITEMAPUSETO` and `NOSEARCHALL`. These variables are used to dynamically generate the [[SiteMap]]
-- TWiki does not edit the [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] to update the `WIKIWEBLIST`. This must be done by hand
-
-<a name="RenameWeb"></a>
-
-## <a name="Renaming or Deleting a Web"></a> Renaming or Deleting a Web
-
-Rename a web via the Tools section in each web's [[WebPreferences]] topic. You may delete a web by moving it into a Trash web.
-
-### <a name="Permissions"></a> Permissions
-
-You may only rename a web if you have permissions to rename all the topics within that web, including any topics in that web's subwebs. You will also need permissions to update any topics containing references to that web.
-
-### <a name="Edit Conflicts"></a> Edit Conflicts
-
-If anyone is editing a topic which requires updating, or which lives in the web being renamed, a second confirmation screen will come up which will indicate which topics are still locked for edit. You may continue to hit the refresh button until an edit lease is obtained for each topic which requires updating (the "Refresh" button will change to "Submit"), or hit "Cancel", which will cancel your edit lease on all affected topics.
-
-### <a name="Renaming the webs in the distrib"></a> Renaming the webs in the distribution
-
-If you plan to rename the Main web, remember that TWiki stores user and group topics in this web. That means that every [[WikiName]] signature - `Main.SomeUserName` - points to it and would need updating (unless the variable, `%MAINWEB%.SomeUserName`, is used throughout). This potentially large change can be performed automatically if you rename the web from the Tools section of [[WebPreferences]], as described above.
-
-%X% If you want to rename the TWiki or Main webs, remember they are referred to in the TWiki configuration. You will need to change the `{SystemWebName}`, `{UsersWebName}` and/or `{LocalSitePreferences}` settings in the configuration using the [configure](http://www.dementia.org/twiki/configure) interface.
+- You must have `ROOTCHANGE` access to create a top-level web (one with no parent)
+- Only the person who created it has permission to change the WebPreferences in the new web
 
 ## <a name="Hierarchical Webs"></a> Hierarchical Webs
 
-Hierarchical web support is enabled by turning on the `{EnableHierarchicalWebs}` setting in [configure](http://www.dementia.org/twiki/configure). Without this setting, TWiki will only allow a single level of hierarchy (webs). If you set this, you can use multiple levels, like a directory tree, i.e. webs within webs.
+You can only create hierarchical webs (webs within webs) if the `{EnableHierarchicalWebs}` setting in [configure](http://www.dementia.org/twiki/configure) is enabled. Hierarchical webs are currently enabled.
 
 **_%T% Note:_** You might not need hierarchical webs. TWiki topics already have a parent/child relationship within a web, which is shown in the breadcrumb. Try to keep the number of webs to a minimum in order to keep search and cross-referencing simple.
 
@@ -118,12 +101,12 @@ To create a subweb named `Bar` inside a web named `Foo`, use `Foo/Bar` or `Foo.B
 
 ### <a name="Subweb Preferences are Inherited"></a> Subweb Preferences are Inherited
 
-The preferences of a subweb are inherited from the parent web and overridden locally. Preferences are ultimately inherited from the [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] topic.
+The preferences of a subweb are inherited from the parent web and overridden locally. Preferences are ultimately inherited from the [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]] topic.
 
 **Example Preference Inheritance for `Sandbox/TestWeb/SubWeb.SubWebTopic` topic:**
 
-1. `TWiki.TWikiPreferences` site-wide preferences
-2. `Sandbox.WebPreferences` inherits from and overrides settings in `TWiki.TWikiPreferences`
+1. `%SYSTEMWEB%.TWikiPreferences` site-wide preferences
+2. `Sandbox.WebPreferences` inherits from and overrides settings in `%SYSTEMWEB%.TWikiPreferences`
 3. `Sandbox/TestWeb.WebPreferences` inherits from and overrides settings in `Sandbox.WebPreferences`
 4. `Sandbox/TestWeb/SubWeb.WebPreferences` inherits from and overrides settings in `Sandbox/TestWeb.WebPreferences`
 5. `Sandbox/TestWeb/SubWeb.SubWebTopic` inherits from and overrides settings in `Sandbox/TestWeb/SubWeb.WebPreferences`
@@ -132,4 +115,28 @@ The preferences of a subweb are inherited from the parent web and overridden loc
 
 The Pattern skin (default) indicates Subwebs by indenting them in the sidebar relative to their level in the hierarchy.
 
+<a name="RenameWeb"></a>
+
+## <a name="Renaming or Deleting a Web"></a> Renaming or Deleting a Web
+
+Rename a web via the Tools section in each [[WebPreferences]] topic. You may delete a web by moving it into a Trash web.
+
+### <a name="Permissions"></a> Permissions
+
+You may only rename a web if you have permissions to rename all the topics within that web, including any topics in that web's subwebs. You will also need permissions to update any topics containing references to that web.
+
+### <a name="Edit Conflicts"></a> Edit Conflicts
+
+If anyone is editing a topic which requires updating, or which lives in the web being renamed, a second confirmation screen will come up which will indicate which topics are still locked for edit. You may continue to hit the refresh button until an edit lease is obtained for each topic which requires updating (the "Refresh" button will change to "Submit"), or hit "Cancel", which will cancel your edit lease on all affected topics.
+
+### <a name="Renaming the webs in the distrib"></a> Renaming the webs in the distribution
+
+It is possible, though not recommended, to change the names of the webs in the distribution.
+
+If you plan to rename the %USERSWEB% web, remember that TWiki stores user topics in this web. That means that every [[WikiName]] signature - `%USERSWEB%.SomeUserName` - points to it and would need updating (unless the variable, `%USERSWEB%.SomeUserName`, is used throughout). This potentially large change can be performed automatically if you rename the web from the Tools section of [[WebPreferences]], as described above.
+
+%X% If you want to rename the %SYSTEMWEB% or %USERSWEB% webs, remember they are referred to in the TWiki configuration. You will need to change the `{SystemWebName}`, `{UsersWebName}` and/or `{LocalSitePreferences}` settings in the configuration using the [configure](http://www.dementia.org/twiki/configure) interface.
+
+%X% Renaming the webs in the distribution is not recommended because it makes upgrades much more complicated.
+
 **_Related Topics:_** [[AdminDocumentationCategory]], [[AdminToolsCategory]]
diff --git a/TWiki/MonitorDotPm.mdwn b/TWiki/MonitorDotPm.mdwn
new file mode 100644 (file)
index 0000000..376bdd9
--- /dev/null
@@ -0,0 +1,25 @@
+# <a name="Package &lt;code&gt;="></a> Package =
+
+<div>
+  <ul>
+    <li><a href="#Package =="> Package ==</a></li>
+  </ul>
+</div>
+
+Monitoring package. Instrument the code like this:
+
+use Monitor; Monitor::MARK("Description of event"); Monitor::MARK("Another event");
+
+or, to monitor all the calls to a module
+
+use Monitor; Monitor::MonitorMethod('TWiki::Users');
+
+or a function
+
+use Monitor; Monitor::MonitorMethod('TWiki::Users', 'getCanonicalUserID');
+
+Then set the environment variable TWIKI\_MONITOR to a perl true value, and run the script from the command line e.g: $ cd bin $ ./view -topic Myweb/MyTestTopic
+
+The results will be printed to STDERR at the end of the run. Two times are shown, a time relative to the last MARK and a time relative to the first MARK (which is always set the first time this package is used). The final column is total memory.
+
+NOTE: it uses /proc - so its linux specific...
index ea91e05..5416471 100644 (file)
@@ -1,199 +1,7 @@
-# <a name="Pattern skin"></a><a name=" Pattern skin"></a> Pattern skin
+Status: 500 Content-type: text/html
 
-**PatternSkin provides 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.
+# Software error:
 
-<div><span>Page contents</span><ul>
-    <li>
-      <ul>
-        <li><a href="#Screenshot"> Screenshot</a></li>
-      </ul>
-    </li>
-    <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
-        <li><a href="#Creating your own look"> Creating your own look</a><ul>
-            <li><a href="#Template customization"> Template customization</a></li>
-            <li><a href="#Style sheet customization"> Style sheet customization</a></li>
-          </ul>
-        </li>
-        <li><a href="#Supported browsers"> Supported browsers</a></li>
-        <li><a href="#Installation"> Installation</a><ul>
-            <li><a href="#Troubleshooting"> Troubleshooting</a></li>
-          </ul>
-        </li>
-        <li><a href="#Skin Info"> Skin Info</a></li>
-        <li><a href="#Related topics"> Related topics</a></li>
-        <li><a href="#Feedback"> Feedback</a></li>
-      </ul>
-    </li>
-  </ul>
-</div>
+    Can't use an undefined value as an ARRAY reference at /tmp/TWiki/lib/TWiki/Prefs.pm line 246.
 
-## <a name="Screenshot"></a> Screenshot
-
-[<img src="http://www.dementia.org/twiki//view/patternskin_screenshot.jpg" width="600" height="130" alt="Click for full screen image" style="border: 1px solid #eee" />](http://www.dementia.org/twiki//view/patternskin_screenshot_full.png)
-
-## <a name="Creating your own look"></a> Creating your own look
-
-### <a name="Template customization"></a> Template customization
-
-[[PatternSkinCustomization]] - how to configure page elements
-
-### <a name="Style sheet customization"></a> Style sheet customization
-
-[[PatternSkinCssCookbook]] - how to customize the visual style
-
-## <a name="Supported browsers"></a> Supported browsers
-
-PatternSkin has been tested successfully 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 2.0.3
-  - Mozilla/Firefox 1.5 (note: Firefox 1.0 will show visual quirks)
-- \*nix
-  - Mozilla/Firefox 1.5 (note: Firefox 1.0 will show visual quirks)
-
-## <a name="Installation"></a> 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 <code>**%TOPIC%.zip**</code> in your twiki installation directory
-- Test if installed: [[http://www.dementia.org/twiki/view/%WEB%/%TOPIC%?skin=pattern|%WEB%/%TOPIC%?skin=pattern]]
-- For skin activation see [[TWikiSkins]]
-
-### <a name="Troubleshooting"></a> 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%
-- TWIKICOLORSURL = %TWIKICOLORSURL%
-- 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 = %PUBURLPATH%/%TWIKIWEB%/PatternSkin/layout.css
-          * Set TWIKISTYLEURL = %PUBURLPATH%/%TWIKIWEB%/PatternSkin/style.css
-          * Set TWIKICOLORSURL = %PUBURLPATH%/%TWIKIWEB%/PatternSkin/colors.css
-
-**NOTE:** customization of these values should be done in [[Main.TWikiPreferences|Main/TWikiPreferences]]
-
-If this still does not work, contact the administrator who installs skins.
-
-For further troubleshooting and feedback, go to TWiki:Plugins/PatternSkinDev. Report bugs in the [[Support web|TWiki:Support/WebHome]].
-
-## <a name="Skin Info"></a> Skin Info
-
-<table border="1" cellpadding="0" cellspacing="0">
-  <tr>
-    <td align="right"> Description: </td>
-    <td> TWiki's default skin; CSS based, flexible and W3C-compliant </td>
-  </tr>
-  <tr>
-    <td align="right"> Screenshot: </td>
-    <td><a href="http://www.dementia.org/twiki//view/patternskin_screenshot_full.png"><img alt="Click for full screen image" height="130" src="http://www.dementia.org/twiki//view/patternskin_screenshot.jpg" style="border: 1px solid #eee" width="600" /></a></td>
-  </tr>
-  <tr>
-    <td align="right"> Preview: </td>
-    <td>[[%WEB%/%TOPIC%?skin=pattern]]</td>
-  </tr>
-  <tr>
-    <td align="right"> Base Name: </td>
-    <td> pattern </td>
-  </tr>
-  <tr>
-    <td align="right"> Skin Author: </td>
-    <td> TWiki:Main/ArthurClemens </td>
-  </tr>
-  <tr>
-    <td align="right"> Skin Version: </td>
-    <td> 15 Jan 2006 (v2.0.6) </td>
-  </tr>
-  <tr>
-    <td align="right"> History: </td>
-    <td>  </td>
-  </tr>
-  <tr>
-    <td align="right"> 15 Jan 2006: </td>
-    <td> v.2.0.6 - TWiki 4.1.0 (Edinburgh) RELEASE VERSION </td>
-  </tr>
-  <tr>
-    <td align="right"> 26 Sep 2006: </td>
-    <td> v.2.0.5 - Fixed form background colors </td>
-  </tr>
-  <tr>
-    <td align="right"> 22 Jul 2006: </td>
-    <td> v.2.0.4 - Refactored info in colors.css; fixed textarea color </td>
-  </tr>
-  <tr>
-    <td align="right"> 26 Jun 2006: </td>
-    <td> v.2.0.3 - TWiki 4.0.3 (Dakar) RELEASE VERSION </td>
-  </tr>
-  <tr>
-    <td align="right"> 31 Jan 2006: </td>
-    <td> v.2.0.0 - TWiki 4.0.0 (Dakar) RELEASE VERSION </td>
-  </tr>
-  <tr>
-    <td align="right"> 28 Aug 2004: </td>
-    <td> v.1.0.9 - TWiki 3.0 (Cairo) RELEASE VERSION </td>
-  </tr>
-  <tr>
-    <td align="right"> 08 Aug 2004: </td>