Changeset 8369


Ignore:
Timestamp:
07/31/10 08:22:19 (22 months ago)
Author:
PaulHarvey
Message:

Item9415: Doc example fixups, Fix FormattedSearch

Location:
trunk/core/data/System
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/core/data/System/FormattedSearch.txt

    r8367 r8369  
    214214---+++ Nested Search 
    215215 
    216 Search, as with almost any TML expression, may be nested. For example, search for some topics, then form a new search for each topic found in the first search. The idea is to build the nested search string using a formatted search in the first search. 
     216[[VarSEARCH][SEARCH]], as with many TML macros, may be nested. For example: search for some topics in an initial (outer) search, and for each of them apply a second (inner) search. The idea is to use the outer search to build a series of inner seraches. 
    217217 
    218218#InsideOutLeftToRight 
    … …  
    228228The macros are expanded in this order: MACRO3, MACRO4, MACRO2, MACRO1. 
    229229 
    230 Consider the following example. Let's search for all topics that contain the word "culture" (first search), and let's find out where each topic found is linked from (second search). 
    231  
    232 *First search:* 
     230Consider the following example. Let's search for all topics that contain the word "culture" (outer search), and find out where each topic found is linked from (inner search). 
     231 
     232*Initial (outer) search:* 
    233233   <verbatim class="tml"> 
    234234%SEARCH{ 
    … …  
    239239}%</verbatim> 
    240240 
    241 *Second search:* 
     241*Second (inner) search:* 
    242242 
    243243For each hit, we want this search: 
    244244   <verbatim class="tml"> 
    245245%SEARCH{ 
    246    "(topic found in first search)" 
     246   "(topic found in outer search)" 
    247247   nosearch="on" 
    248248   nototal="on" 
    … …  
    253253Now let's nest the two. 
    254254---++++ Method 1 (traditional) 
    255 The second search cannot be placed directly into the format string of the first, because of the "inside-out, left-to-right" macro expansion behaviour discussed earlier. It must be delayed so that the outer search is evaluated first. To do this, we need to escape the second search, i.e. let the first search build a series of searches using the second search. 
    256    * Use =$percent= to escape (delay) the second search's [[VarSEARCH][SEARCH]] macro 
     255The inner search cannot be placed directly into the format string of the outer, because of the "inside-out, left-to-right" macro expansion behaviour [[#InsideOutLeftToRight][discussed earlier]]. It must be delayed so that the outer search is evaluated first. To do this, we need to escape the inner search, i.e. let the outer search build a series of searches comprised of the inner search. 
     256   * Use =$percent= to escape (delay) the inner search's [[VarSEARCH][SEARCH]] macro 
    257257   * Use =\"= to escape the double quotes 
    258258   * Use =$dollar= to escape the =$= of =$topic= 
    … …  
    295295Nested expressions can be difficult to write correctly, and are difficult to troubleshoot when they go wrong. 
    296296 
    297 The recommended approach is to make use of the [[VarSTARTSECTION][STARTSECTION]]/[[VarENDSECTION][ENDSECTION]] feature of the [[VarINCLUDE][INCLUDE]] macro. Instead of nesting the second search expression directly inside the format string of the first, the second search is written as a separate stand-alone section of a topic which is INCLUDEd into the format string of the first. 
     297The recommended approach is to make use of the [[VarSTARTSECTION][STARTSECTION]]/[[VarENDSECTION][ENDSECTION]] feature of the [[VarINCLUDE][INCLUDE]] macro. Instead of nesting the inner search expression directly inside the format string of the outer, the inner search is written as a separate stand-alone section of a topic which is INCLUDEd into the format string of the outer. 
    298298 
    299299*Write this:* 
    … …  
    308308}% 
    309309 
    310 <!-- HTML comment to hide this section from the user 
     310<!-- HTML comment to hide this section from the user. verbatim prevents the section being evaluated 
     311<verbatim> 
    311312%STARTSECTION{"mysearch"}%%SEARCH{ 
    312313   "%thetopic%" 
    … …  
    316317   separator=", " 
    317318}%%ENDSECTION{"mysearch"}% 
     319</verbatim> 
    318320--> 
    319321</verbatim> 
    … …  
    321323%ICON{"info"}% Output will be the same as for the first method 
    322324 
    323 <blockquote>%ICON{"warning"}% Nested search can be slow, especially if you nest more then 3 times. Nesting is limited to 16 levels. 
     325<blockquote>%ICON{"warning"}% Nested search can be slow, especially if you nest more then 3 deep. Nesting is limited to 16 levels. 
    324326 
    325327When using the traditional method for nesting macros, each new nesting level must "escape the escapes", e.g. write =$dollarpercentSEARCH{= for level three, =$dollardollarpercentSEARCH{= for level four, etc. Therefore it is strongly advised to use the sectional include method instead, which avoids this kind of difficult and error-prone syntax.</blockquote> 

  • trunk/core/data/System/InstantEnhancements.txt

    r4884 r8369  
    6464 
    6565For instance, if we want to write =%<nop>DOWN%= instead of =%<nop>ICON{"arrowbdown"}%=, define the new macro like this: 
    66 <verbatim> 
     66%JQREQUIRE{"chili"}%<verbatim class="tml"> 
    6767   * Set DOWN = %ICON{"arrowbdown"}% 
    6868</verbatim> 
    6969Or if you have a custom image to use, attach this to [[%LOCALSITEPREFS%]] and write: 
    70 <verbatim> 
     70%JQREQUIRE{"chili"}%<verbatim class="tml"> 
    7171   * Set DOWN = <img src="%ATTACHURL%/my_image.gif" border="0" alt="DOWN" width="16" height="16" /> 
    7272</verbatim> 
    … …  
    115115---+++ Personal directory of topics you're involved in 
    116116 
    117 Here's how you can create your own personal directory of topics you've contributed to recently. Copy the text below (between *Start Copy* and *End Copy*) and paste it into your personal page (%WIKIUSERNAME%). You can add other webs to search by duplicating one of the web subsections and editing the string {web ="webname"} in the search parameters to refer to the specific web you want to search. This script would also work for a group. 
     117Here's how you can create your own personal directory of topics you've contributed to recently (assuming that your [[VarWIKIUSERNAME][username]] is present on topics that you contribute to). Copy the text below and paste it into your personal page (%WIKIUSERNAME%). You can add other webs to search by duplicating one of the web subsections and editing the string {web ="webname"} in the search parameters to refer to the specific web you want to search. 
    118118 
    119 *Start Copy* 
    120 <verbatim> 
     119<verbatim class="tml"> 
    121120*Here's a list of topics I've been involved in recently:* 
    122121 
    123122---++++ Project Web 
     123%SEARCH{ 
     124   "%TOPIC%" 
     125   web="Project" 
     126   scope="text" 
     127   nonoise="on" 
     128   order="modified" 
     129   reverse="on" 
     130   limit="20" 
     131}% 
     132</verbatim> 
    124133 
    125 %SEARCH{ "%TOPIC%" web="Project" scope="text" nosearch="on" nosummary="on" noheader="on" nototal="on" order="modified" reverse="on" limit="20"}% 
    126  
    127 </verbatim> 
    128 *End Copy* 
    129  
    130 The [[VarSEARCH][SEARCH macro]] has many more formatting options. 
     134Read the [[VarSEARCH][SEARCH documentation]] for more about [[VarSEARCH][SEARCH]]. 
    131135 
    132136---+++ Recently changed pages  
    133137Here are the last 15 changed pages, formatted into a neat table. 
    134138 
    135 <verbatim> 
    136 <table> 
    137 %SEARCH{ "'1'" scope="topic" type="query" nosearch="on" nototal="on" order="modified" reverse="on"  format="<tr><td>  [[$topic][$topic]] </td><td>  $wikiusername  </td><td> $date  </td></tr>" limit="15" }% 
    138 </table> 
     139<verbatim class="tml"> 
     140%SEARCH{ 
     141   "1" 
     142   type="query" 
     143   nonoise="on" 
     144   order="modified" 
     145   reverse="on" 
     146   limit="15" 
     147   header="| *Topic* | *User* | *Date* |" 
     148   format="|  [[$web.$topic][$topic]] | $wikiusername | $date  |" 
     149}% 
    139150</verbatim> 
    140151 
    … …  
    142153 
    143154When 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 ==Edit==. 
    144    * *Example:* ==Set ALLOWTOPICCHANGE = <nop>%USERSWEB%.UserName, <nop>%USERSWEB%.GroupName== 
     155   * *Example:* <verbatim class="tml">   * Set ALLOWTOPICCHANGE = %USERSWEB%.UserName, %USERSWEB%.GroupName</verbatim> 
    145156   * %T% *To hide the setting:* Use HTML comment tags - put ==&lt;!--== on the line _above the setting, and ==--&gt;== on the line below. 
    146157 
    … …  
    148159 
    149160If you want to change the logo per web, simply attach a new logo.gif to the web's <nop>WebPreferences, and change the logo's filename by overriding the name using WEBLOGONAME in <nop>WebPreferences:   
    150    * =Set WEBLOGONAME = filename.gif= 
     161<verbatim class="tml">   * Set WEBLOGONAME = filename.gif</verbatim> 
    151162 
    152163Other cusomtisations are possible using =WEBLOGOIMG=, =WEBLOGOURL=, and =WEBLOGOALT= (they mirror the =WIKILOGO*= macros, but are applied to each web, rather than to the %<nop>WIKITOOLNAME%-based references) 
    153164 
    154165If you'd like to have the same customised logo for all the webs, make these changes in %LOCALSITEPREFS% instead of each web's <nop>WebPreferences, e.g., 
    155    * =Set WEBLOGOIMG = %<nop>PUBURLPATH%/%USERSWEB%/WebPreferences/mylogo.gif= 
     166<verbatim class="tml">   * Set WEBLOGOIMG = %PUBURLPATH%/%USERSWEB%/WebPreferences/mylogo.gif</verbatim> 
    156167 
    157168---++ Customize Topic Classification Forms 
    … …  
    159170With a simple one or two-line default topic form available for every topic  - in *Edit* mode, click the ==[Add]== button, and select the form if it isn't already enabled. Then, click the title to get to the actual form, ==[Edit]==, and carefully change values, probably basic page classifications. You'll get some increased value, and hands-on experience with DataForms, without having to read up about them first. %X% *(add the corresponding search per category - copy a default and change)* 
    160171 
     172---++ Customize The Left Navigation Bar 
     173<blockquote>%ICON{"info"}% This advice applies to sites using the default PatternSkin</blockquote> 
     174 
     175Customize the contents of the WebLeftBar topic, which does not exist by default - read PatternSkinCustomization for details. Each web has its own WebLeftBar that may include important topics for that web, or link to an important topic for the overall site. 
     176 
     177<blockquote>%T% Also check PatternSkinCustomization to learn how to customise the WebTopBar</blockquote> 
    161178 
    162179---++ Add Your Favorite <nop>JavaScript Features 
    163180 
    164 You're no doubt familiar or better with HTML, JS, and "webmastering". Without getting into the [[skin templates]] system yet, you can easily edit the ==view.pattern.tmpl== (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 macros. Open up some space in the ==&lt;head&gt;== area, and you can drop in reliable <nop>JavaScripts - a pop-up window script, for example - or tag it as an external script. 
     181You're no doubt familiar or better with HTML, JS, and "webmastering". To add custom javascript and/or css to the page, the [[VarADDTOZONE][ADDTOZONE]] macro is used. Without getting into the [[skin templates]] system just yet, the easiest place to put [[VarADDTOZONE][ADDTOZONE]] macros is in some topic that is used by your site skin for every page view, such as the WebLeftBar if using the default PatternSkin. 
    165182 
    166    * %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* 
     183To add in-line javascript, read the [[VarADDTOZONE#ExampleAddingJS][javascript example]]. 
    167184 
    168 %X% Depending on what you load up, you may change the overall cross-browser compatibility - however be careful that your site does not look beat up in various other browsers. The scripts you choose will determine compatibility. 
     185Alternatively, make use of the =LIBJS= template, which simplifies the process of adding .js files to the page: 
     186<verbatim class="tml"> 
     187%TMPL:P{"LIBJS" id="MyJQueryPlugin/jquery.myplugin" requires="JQUERYPLUGIN"}% 
     188</verbatim> 
    169189 
    170 ---++ Customize The Left Navigation Bar 
     190This assumes that there is a file named [[%PUBURLPATH%/%SYSTEMWEB%/MyJQueryPlugin/jquery.myplugin%FWSRC%.js]] 
    171191 
    172 Customize the contents of the WebLeftBar for each web to include important topics for that web, or to link to an important topic for the overall site. Each web has its own WebLeftBar page. (This is specific to the PatternSkin.)  
     192---+++ Adding CSS 
     193See [[VarADDTOZONE][ADDTOZONE]]'s [[VarADDTOZONE#ExampleAddingCSS][CSS example]] 
     194 
     195%X% Depending on what you load up, you may change the overall cross-browser compatibility - be careful that your site does not look beat up in various other browsers. The scripts and CSS features you choose will determine compatibility. 
    173196 
    174197---- 

  • trunk/core/data/System/VarADDTOZONE.txt

    r8347 r8369  
    7474   By contrast, as explained earlier - when ={OptimizePageLayout}= is disabled (default) - Foswiki is able resolve such dependencies successfully. 
    7575 
     76#ExampleAddingJS 
    7677---+++ Example: Adding Javascript to a page 
    7778   * Make sure that all inline Javascript code in the topic (if it is allowed) 
    … …  
    7980     with the appropriate library-id to guarantee a correct load order. For example, jQuery code should be added as follows: 
    8081     %JQREQUIRE{"chili"}%<verbatim class="js"> 
    81      %JQREQUIRE{"shake"}%%ADDTOZONE{ 
    82          "body" 
    83          id="MyApp::ShakePart" 
    84          text=" 
    85          <script type='text/javascript'> 
    86             jQuery('#something').shake(3, 10, 180); 
    87          </script>" 
    88          requires="JQUERYPLUGIN::SHAKE" 
    89      }%</verbatim> where "MyApp::ShakePart" is a unique =id= to identify the text added to body; and =JQUERYPLUGIN::SHAKE= signifies that the content added with that identifier should appear beforehand. 
     82%JQREQUIRE{"shake"}%%ADDTOZONE{ 
     83   "body" 
     84   id="MyApp::ShakePart" 
     85   text=" 
     86   <script type='text/javascript'> 
     87      jQuery('#something').shake(3, 10, 180); 
     88   </script>" 
     89   requires="JQUERYPLUGIN::SHAKE" 
     90}%</verbatim> where "MyApp::ShakePart" is a unique =id= to identify the text added to body; and =JQUERYPLUGIN::SHAKE= signifies that the content added with that identifier should appear beforehand. 
    9091 
     92#ExampleAddingCSS 
     93---+++ Example: Adding CSS to a page 
     94<verbatim class="tml"> 
     95%ADDTOZONE{"head" 
     96   id="MyCSS" 
     97   text=" 
     98      <style type='text/css' media='all'> 
     99         @import url('%PUBURLPATH%/%SYSTEMWEB%/MyCSS/foo.css'); 
     100      </style>" 
     101}% 
     102</verbatim> 
    91103See also [[VarRENDERZONE][RENDERZONE]], 
    92104[[http://foswiki.org/Development/UsingADDTOZONE][Using ADDTOZONE]] 
Note: See TracChangeset for help on using the changeset viewer.