Changeset 702


Ignore:
Timestamp:
11/15/08 13:21:07 (4 years ago)
Author:
CrawfordCurrie
Message:

Item109: terminology fixes

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/core/data/TWiki/Macros.txt

    r696 r702  
    77 
    88Macros are text strings - =%<nop>MACRONAME%= or =%<nop>MACRONAME{ parameter="value" }%= - that expand into content whenever a topic is rendered for viewing. There are two types of macros: 
    9    1 Preferences macros: Can be defined and changed by the user 
     9   1 Preference settings: Can be defined and changed by the user 
    1010   1 Predefined macros: Defined by the TWiki system or by Plugins (for example, the SpreadSheetPlugin introduces a =%<nop>CALC{}%= macro) 
    1111 
    … …  
    1515 
    1616To use a macro type its name. For example, 
    17    * type =%<nop>T%= to get %T% (a preferences macro) 
    18    * type =%<nop>TOPIC%= to get =%TOPIC%= (a predefined macro) 
    19    * type =%<nop>CALC{ "$UPPER(Text)" }%= to get =TEXT= (a macro defined by Plugin) 
     17   * type =%<nop>T%= to get %T% (a [[%SYSTEMWEB%.PreferenceSettings][preference settings]]) 
     18   * type =%<nop>TOPIC%= to get =%TOPIC%= (a predefined [[macro]]) 
     19   * type =%<nop>CALC{ "$UPPER(Text)" }%= to get =TEXT= (a [[macro]] defined by a Plugin) 
    2020 
    2121__Note:__ 
    … …  
    3030 
    3131#SettingPrefs 
    32 #PreferencesVariables 
    3332#PreferencesMacros 
    34 ---++ Preferences Macros 
     33---++ Preferences 
    3534 
    36 Unlike predefined macros, preferences macros can be defined by the user in various places. 
     35_Preferences settings_ are simple macros that do _not_ accept parameters, and are 
     36defined in topics. A lot of the macros you will encounter are of this type. 
    3737 
    38 ---+++ Setting Preferences Macros 
     38Preferences can be defined by the user in various places. 
     39 
     40---+++ Setting Preferences 
    3941You can set macros in all the following places: 
    40    1 local site level in [[%SYSTEMWEB%.DefaultPreferences][%SYSTEMWEB%.DefaultPreferences]] 
     42   1 default level in [[%SYSTEMWEB%.DefaultPreferences][%SYSTEMWEB%.DefaultPreferences]] (*not* recommended) 
    4143   1 plugin topics (see [[Plugins]]) 
    4244   1 local site level in [[%LOCALSITEPREFS%][%LOCALSITEPREFS%]] 
    4345   1 user level in individual user topics in %USERSWEB% web 
    44    1 web level in %WEBPREFSTOPIC% of each web 
     46   1 web level in %WEBPREFSTOPIC% of a parent web 
     47   1 web level in %WEBPREFSTOPIC% of the web 
    4548   1 topic level in topics in webs 
    4649   1 session macros (if sessions are enabled) 
    … …  
    4851Settings at higher-numbered levels override settings of the same macro at lower numbered levels, unless the macro was included in the setting of FINALPREFERENCES at a lower-numbered level, in which case it is locked at the value it has at that level. 
    4952 
    50 If you are setting a macro and using it in the same topic, note that TWiki reads all the macro settings from the saved version of the topic before it displays anything.  This means you can use a macro anywhere in the topic, even if you set it somewhere inconspicuous near the end. *But beware:*  it also means that if you change the setting of a macro you are using in the same topic, ==Preview== will show the wrong thing, and you must ==Save== the topic to see it correctly. 
     53If you are setting a preference and using it in the same topic, note that TWiki reads all the [[%SYSTEMWEB%.PreferenceSettings][preference settings]] from the saved version of the topic before it displays anything.  This means you can use a macro anywhere in the topic, even if you set it somewhere inconspicuous near the end. *But beware:*  it also means that if you change the setting of a macro you are using in the same topic, ==Preview== will show the wrong thing, and you must ==Save== the topic to see it correctly. 
    5154 
    5255The syntax for setting macros is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets): <br /> =[multiple of 3 spaces] * [space] Set [space] MACRONAME [space] = [space] value= 
    … …  
    6972<blockquote> 
    7073*Example: Create a custom logo macro* <br /> 
    71    * To place a logo anywhere in a web by typing ==%<nop>MYLOGO%==, define the Macro on the web's WebPreferences topic, and upload a logo file, ex: =mylogo.gif=. You can upload by [[FileAttachment][attaching the file]] to WebPreferences, or, to avoid clutter, to any other topic in the same web, e.g. =LogoTopic=. Sample macro setting in WebPreferences: 
     74   * To place a logo anywhere in a web by typing ==%<nop>MYLOGO%==, define the [[%SYSTEMWEB%.PreferenceSettings][preference settings]] on the web's WebPreferences topic, and upload a logo file, ex: =mylogo.gif=. You can upload by [[FileAttachment][attaching the file]] to WebPreferences, or, to avoid clutter, to any other topic in the same web, e.g. =LogoTopic=. Sample preference setting in WebPreferences: 
    7275      * ==<nop>Set MYLOGO = %<nop>PUBURL%/%<nop>WEB%/LogoTopic/mylogo.gif== 
    7376</blockquote> 
    7477 
    75 You can also set preferences macros on a topic by clicking the link =Edit topic preference settings= under =More topic actions=. Preferences set in this manner are not visible in the topic text, but take effect nevertheless. 
     78You can also set [[%SYSTEMWEB%.PreferenceSettings][preference settings]] in a topic by clicking the link =Edit topic preference settings= under =More topic actions=. Preferences set in this manner are not visible in the topic text, but take effect nevertheless. 
    7679 
    77 ---+++ Access Control Macros 
     80---+++ Access Control Settings 
    7881 
    79 These are special types of preferences macros to control access to content. AccessControl explains these security settings in detail. 
     82These are special types of preference settings to control access to content. AccessControl explains these security settings in detail. 
    8083 
    81 ---+++ Local values for macros 
     84---+++ Local values for preferences 
    8285Certain topics (a users home topic, web site and default preferences topics) have a problem; macros defined in those topics can have two meanings. For example, consider a user topic. A user may want to use a double-height edit box when they are editing their home topic - but *only* when editing their home topic. The rest of the time, they want to have a normal edit box. This separation is achieved using =Local= in place of =Set= in the macro definition. For example, if the user sets the following in their home topic: 
    8386<verbatim> 
    … …  
    9093Use this powerful feature with great care! =%<nop>ALLVARIABLES%= can be used to get a listing of the values of all macros in their evaluation order, so you can see macro scope if you get confused. 
    9194 
    92 ---+++ Frequently Used Preferences macros 
     95#PreDef 
     96---++ Predefined Macros 
    9397 
    94 The following macros are frequently used in topic content. They are defined in DefaultPreferences#Miscellaneous_Settings: 
     98Most predefined macros return values that were either set in the configuration when TWiki was installed, or taken from server info (such as current username, or date and time). Some, like =%<nop>SEARCH%=, are powerful and general tools. 
     99 
     100   * %X% Predefined macros can be overridden by [[%SYSTEMWEB%.PreferenceSettings][preference settings]] (except TOPIC and WEB) 
     101   * %X% Plugins may extend the set of predefined macros (see individual Plugins topics for details) 
     102   * %T% *Take the time to thoroughly read through ALL preference macros.* If you actively configure your site, review macros periodically. They cover a wide range of functions, and it can be easy to miss the one perfect macro for something you have in mind. For example, see =%<nop>INCLUDINGTOPIC%=, =%<nop>INCLUDE%=, and the mighty =%<nop>SEARCH%=. 
     103 
     104This version of TWiki - %WIKIVERSION% - predefines the following macros: 
     105 
     106%SEARCH{ 
     107    "^Var[A-Z_0-9]+$" 
     108    casesensitive="on" 
     109    type="regex" 
     110    scope="topic" 
     111    format="$percntINCLUDE{$web.$topic}$percnt" 
     112    nonoise="on" 
     113}% 
     114 
     115---+++ Shortcuts 
     116 
     117The following macros are [[%SYSTEMWEB%.PreferenceSettings][preference settings]] and are frequently used in topic content. 
    95118   * =%<nop>BR%= - line break 
    96119   * =%<nop>BULLET%= - bullet sign 
    … …  
    110133   * =%<nop>Y%= - %Y% Done icon 
    111134 
    112 !There are additional useful preferences macros defined in DefaultPreferences, in [[%LOCALSITEPREFS%]], and in WebPreferences of every web. 
    113  
    114 #PreDef 
    115 ---++ Predefined Macros 
    116  
    117 Most predefined macros return values that were either set in the configuration when TWiki was installed, or taken from server info (such as current username, or date and time). Some, like =%<nop>SEARCH%=, are powerful and general tools. 
    118  
    119    * %X% Predefined macros can be overridden by [[#PreferencesMacros][preferences macros]] (except TOPIC and WEB) 
    120    * %X% Plugins may extend the set of predefined macros (see individual Plugins topics for details) 
    121    * %T% *Take the time to thoroughly read through ALL preference macros.* If you actively configure your site, review macros periodically. They cover a wide range of functions, and it can be easy to miss the one perfect macro for something you have in mind. For example, see =%<nop>INCLUDINGTOPIC%=, =%<nop>INCLUDE%=, and the mighty =%<nop>SEARCH%=. 
    122  
    123 This version of TWiki - %WIKIVERSION% - predefines the following macros: 
    124  
    125 %SEARCH{ 
    126     "^Var[A-Z_0-9]+$" 
    127     casesensitive="on" 
    128     type="regex" 
    129     scope="topic" 
    130     format="$percntINCLUDE{$web.$topic}$percnt" 
    131     nonoise="on" 
    132 }% 
     135See ShortcutMacros for a full list of predefined shortcuts. 
    133136 
    134137%ENDSECTION{type="include"}% 
Note: See TracChangeset for help on using the changeset viewer.