##master-page:HelpOnMacros
##master-date:[[DateTime(2006-10-26T23:51:39Z)]]
#acl -All:write Default
#format wiki
#language zh-tw
<<Navigation(children)>> <<TableOfContents>>

== 巨集 ==
在wiki頁面嵌入巨集，以引入系統功能。試著編輯[[最新更動]]或[[系統資訊]]，就知道是怎麼回事了。

更多的標記資訊請參照[[說明/編輯頁面]]。

=== 搜尋巨集 ===
目前MoinMoin使用的新搜尋引擎，提供支援複雜型態的互動式搜尋，以及嵌入頁面的搜尋巨集。詳細說明請參照[[說明/搜尋本站]]。

||<tablewidth="100%">'''巨集''' ||'''功能''' ||'''範例''' ||
||||||`<<AdvancedSearch>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 於頁面中嵌入「進階搜尋」對話框 || 請見[[尋找頁面]] ||
||||||`<<TitleSearch>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 於頁面中嵌入「搜尋頁面標題」對話框 || 請見[[尋找頁面]] ||
||||||`<<FullSearch>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 於頁面中嵌入「全文檢索」對話框 || 請見[[尋找頁面]] ||
||||||`<<FullSearch()>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出內容包含此頁面標題（頁面名稱）的所有頁面，其作用與點選頁面標題連結相同。 || 請見CategoryCategory ||
||||||`<<FullSearch(text)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出內容包含檢索詞的所有頁面 || Search for {{{powered}}}:<<FullSearch(powered)>> ||
||||||`<<FullSearchCached(text)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 功能同{{{FullSearch}}}巨集，並將搜尋結果放入快取，下次執行時直接讀入快取資料。當您覺得速度比即時性（up-to-date）重要，就用它吧！ || Search for {{{powered}}}:<<FullSearchCached(powered)>> ||
||||||`<<GoTo>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 於頁面中嵌入「跳至此頁」對話框 || 請見[[尋找頁面]] ||
||||||`<<PageList(Help)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出標題（名稱）包含檢索詞的所有頁面 || 請見[[說明/索引]] ||

=== 導覽 ===
||<tablewidth="100%">'''巨集''' ||'''功能''' ||'''範例''' ||
||||||`<<RecentChanges>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出最近更動過的頁面 || 請見[[最新更動]] ||
||||||`<<TitleIndex>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出所有頁面標題 || 請見[[標題索引]] ||
||||||`<<WordIndex>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出所有頁面標題中詞彙（如 WikiName 包含兩個詞彙 Wiki 和 Name） || 請見[[詞彙索引]] ||
||||||`<<WantedPages>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出被連結但還不存在的頁面 || 請見[[未定義頁]] ||
||||||`<<OrphanedPages>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出沒有被其它頁面連結的頁面 || 請見[[孤立頁面]] ||
||||||`<<AbandonedPages>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出很久沒有變動的頁面 || 請見[[遺棄頁面]] ||
||||||`<<RandomPage>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 隨機嵌入一個頁面連結 || <<RandomPage>> ||
||||||`<<RandomPage(#)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 隨機嵌入指定數量的頁面連結 || 兩個隨機頁面：<<RandomPage(2)>> ||
||||||`<<TableOfContents([maxdepth])>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 顯示內容目錄，可限制顯示的層數。 || 見本頁頁首 ||
||||||`<<Anchor(anchorname)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 在指定位置插入錨點 || <<Anchor(here)>>#here ||
||||||`<<Navigation(children[,maxdepth])>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出所有子頁面 || 請見本頁頁首 ||
||||||`<<Navigation(siblings[,maxdepth])>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出同屬於父頁面的頁面 || See HelpOnMacros/MailTo ||
||||||`<<Navigation(slideshow)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 嵌入簡報功能表 || 請見[[說明/簡報]] ||
||||||`<<Navigation(slides)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 嵌入首頁/上頁/下頁/末頁連結 || 請見[[說明/簡報]] ||
||||||`<<AttachInfo>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> displays number of attachments for current page || See HelpOnActions/AttachFile ||
||||||`<<AttachInfo(page)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> displays number of attachments for page || See HelpOnActions/AttachFile ||
||||||`<<AttachList>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出本頁附件 || See HelpOnActions/AttachFile ||
||||||`<<AttachList(page)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出指定頁面的附件 || See HelpOnActions/AttachFile ||

=== 系統資訊 ===
||<tablewidth="100%">'''巨集''' ||'''功能''' ||'''範例''' ||
||||||`<<InterWiki>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出所有已知Wiki站際的站名（InterWiki names） || [[Wiki站際]] ||
||||||`<<SystemInfo>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 關於wiki系統、python直譯器及主機系統的資訊。 || [[系統資訊]] ||
||||||`<<PageCount(exists)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 顯示本站頁面數量。若加上參數{{{exists}}}，將只計算存在的面頁數量。 || 共<<PageCount>>頁 ||
||||||`<<PageSize>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出所有頁面的容量 || 請見[[頁面大小]] ||
||||||`<<StatsChart(type)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 顯示統計圖表 (目前項目有︰點擊次數、頁面大小及瀏覽器） || 請見[[事件統計]]與其子頁面 ||
||||||`<<SystemAdmin>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 給系統管理員的資訊 || 必須有管理權限<<BR>> <<SystemAdmin>> ||
||||||`<<EditedSystemPages>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 列出修改過的系統頁面 || <<EditedSystemPages>> ||

=== 其它 ===
||<tablewidth="100%">'''巨集''' ||'''功能''' ||'''範例''' ||
||||||`<<ImageLink(image,target[,width=width[,height=height]][,alt=alttag])>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 本巨集用來製作圖形連結。圖形參數可以用附件或URL；連結參數可為URL或wiki頁面；額外參數則用來調整圖形大小。若無連結參數，則連結將指向圖形本身。 || See HelpOnMacros/ImageLink ||
||||||`<<Icon(image)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 顯示系統圖示 || 請見[[說明/瀏覽本站]] ||
||||||`<<UserPreferences>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 嵌入「使用者設定」對話框 || 請見[[說明/使用者設定]] ||
||||||`<<UserPreferences(createonly)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 嵌入「使用者註冊」對話框 || ||
||||||`<<BR>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 插入換行符號 || 1st line<<BR>>2nd line ||
||||||`<<RandomQuote(pagename)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> Select a random quote from the given page, or from {{{FortuneCookies}}} if ommitted || <<RandomQuote>> ||
||||||`<<Include(HelloWorld[,"heading"[,level]])>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 引入另一頁面內容 || 詳情請見[[HelpOnMacros/Include]] ||
||||||`<<FootNote(text)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 加入腳注<<FootNote(不可以wiki標記修飾腳注文字)>>。無巨集參數時，將於書寫處嵌入腳注列表。 || 請見底下範例 ||
||||||`<<Date(timestamp)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 依系統設定格式顯示日期。 || <<Date>> ||
||||||`<<DateTime(timestamp)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 依系統設定格式顯示日期時間<<FootNote(參數「timestamp」可為空白（顯示當下日期時間），從1970年至今秒數（unix timestamp），或者w3C 時間格式（如2002-01-23T12:34:56）。請參考RFC822第五節。)>>。 || <<DateTime>> ||
||||||`<<GetText(text)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 讀取I18N文字（主要用於說明頁面） || "Edit``Text"被翻譯為「<<GetText(EditText)>>」 ||
||||||`<<GetText2(,message,argument1,argument2,...)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> loads I18N texts (mainly intended for use on Help pages or in generated output on wiki pages) and replaces `%s` in the message by the arguments. The first character of the argument is used as the separator (in this example: a comma). You can escape the separator by using a backslash. || "`<<GetText2(,[You may not read %s],FooBar)>>`" yields "<<GetText2(,[You may not read %s],FooBar)>>" ||
||||||`<<TeudView>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> useful for intranet developer wikis, a means to view pydoc documentation, formatted via a XSLT stylesheet || See http://twistedmatrix.com/wiki/python/TeudProject ||
||||||`<<MailTo(email)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> 防止垃圾郵件的Email表示法 || 詳情請見 HelpOnMacros/MailTo ||
||||||`<<NewPage(PageTemplate,ButtonLabel,[ParentPage,@ME,@SELF] [,NameTemplate])>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> Allow the user to create (sub-) pages easily, using the page {{{PageTemplate}}}as the template for the new page and the string {{{NameTemplate}}} as a template for the name.<<FootNote(`NameTemplate` is formatted with `time.strftime()`, with the exception of `%s` which is replaced by the input into the edit box (which is only shown if necessary). If `NameTemplate` is not specified or empty, it defaults to `%s`.)>> `@ME` is used if you want the  page created below the users homepage. `@SELF` is used to create a subpage below the page where it is called from. || <<NewPage(CategoryTemplate, Create new category,,Category%s)>> ||
||||||`<<GetVal(NeatSnippets,regards)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> Retrieve dictionary entries from dict pages. || If you have a page called GermanDict which contains the entry ''Test'', you should see the translation here: <<GetVal(GermanDict,Test)>> ||
||||||`<<MonthCalendar(,,12)>>` ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> Displays a Calendar and creates link for entries to each day on subpages || See HelpOnMacros/MonthCalendar ||
<<FootNote>>

=== 動手寫巨集 ===
Create a python file called {{{MacroName.py}}} located in your {{{data/plugin/macro}}} directory. Ensure it has a single method called {{{execute(macro, arguments)}}}, which is the entry-point.

 * ''macro'' is an instance of class Macro, and also evaluates to a string of the macroname.
 * ''arguments'' is an arbitrary argument string you can pass in with parameters to your macro.
All {{{Macro}}} instances have a {{{request}}} member through which you can access the form parameters and other information related to user interaction.

{{{execute()}}} should use the formatter to construct valid markup for the current target format. In most cases this is HTML, so writing a macro which returns HTML will work in most cases but fail when formats like XML or {{{text/plain}}} are requested.

For example, your wiki page has the following line on it:

{{{
<<MacroName(arg1,arg2,arg3)>>
}}}
You could write a !MacroName.py file like this:

{{{
#!python
Dependencies = []
def execute(macro, args):
    return macro.formatter.text("I got these args from a macro %s: %s" %
    (str(macro), args))
}}}
 . /!\ Add an entry into {{{Dependencies}}} if the output from your macro should not be cached. This is important if the macro output could change from one moment to another, for example if your macro searches in wiki pages which may be being edited by other users, or loads information from an external database whose contents may change. Currently the value of any entry does not matter and may be considered a short description for 'why results from this macro should not be cached', but please look at the entries used in other macros for values which may be suitable.
<<FootNote>>
