Scripts

Remarks:
• Python and Python scripts are no real subject of this Wiki for the simple reason that the author has no Python experience. This page on scripting will therefore be limited to whatever wikidpadhelp.wiki had to say on the subject and what the author has retained from his earlier programming days.
• The examples on this page only work with an appropriately relaxed security setting.

Top

In-editor evaluation

Python expressions can be evaluated directly in the editor by typing it, selecting it and pressing Ctrl-E. If you for instance type "1+2+3", select it an press Ctrl-E, then the result will be, that "1+2+3" is expanded to "1+2+3 = 6".
This facility is intended for one-off use; for instance when you need to calculate something and you haven't got a calcuator on hand.

Remarks:
• If the option "Script security" is set to "No scripts" (default), then also in-editor evaluation is disabled. See "Editor scripts".
• Certain functions from the "EvalLibrary.py" library can also be used. See "Evaluation insertions".
• Python functions can nót be used.

Warning!
• If Ctrl-E is pressed withóut any text selected, then instead áll the editor scripts are executed. See "Editor scripts"

Top

Evaluation insertion

General

The eval insertion evaluates a Python expression and in preview and html export replaces the insertion with the result of the evaluation. See also WpInsertions. If the expression contains special characters, then enclose it in quotation characters.

To be honest, this insertion has a véry limited usefullness; there are however three functions available in the "EvalLibrary.py" library, that you can use to put a date and/or time on a page. In preview that would however álways be the current date and/or time. In exported html pages their result would reflect the date and/or time of export.

Examples

[:eval:"5+6"] = 11
[:eval:lib.date()] = 03.12.08
[:eval:lib.time()] = 05:16
[:eval:lib.now()] = 03.12.08 05:16

Remarks:
• Python functions can nót be used.

Security concerns

Because the execution of scripts is a potential security risk, álso within insertions, it can be disabled.

• Process insertion scripts
Enables or disables the evaluation of eval insertions.

Top

Editor scripts

General

Scripts are blocks of code specified somewhere on a wiki page that can be executed using Ctrl-E or Ctrl-1 through to Ctrl-6. Scripts can only be executed in the editor and are meant to simplify your life in maintaining your wiki pages. Scripts are defined within a <% ... %> block, like in the example below:

<%
editor.GotoPos(editor.GetLength())
editor.AddText('\nhello ')
%>

This script would move the cursor to the end of the page and insert the word "hello" on a new line. If you would remove the <<pre ... >> block from the example, you could execute the script by pressing Ctrl-E. Be carefull however, since Ctrl-E will execute áll the scripts on this page. Script blocks are ignored in preview and html export.

Another example would be this script:

<% 3: lib.encodeSelection(editor) %>

If you would type the text "c:\this path\will be encoded.txt", select it and press Ctrl-3, then the text would be converted to: "file:///C|/this%20path/will%20be%20encoded.txt"

Remarks:
• For a list of editor control functions that you have available in scripts, see: Yellowbrain guide to wxPython; this however is a programmer reference and not an (end)user reference.
• "lib.encodeSelection(editor)" is a function in EvalLibrary.py.

Security concerns

Because the execution of scripts is a potential security risk, script execution is disabled by default. To enable it, open the "Options" dialog, chapter "Security", item "Script security" and choose the level of security needed:

• No scripts (default)
Script execution is completely disabled; álso for "In-editor evaluation".

• No import_scripts
Scripts on the currently open page can be executed and expressions evaluated, but importing scripts from other pages is disabled.

• No global.import_scripts
Local "import_scripts" is enabled, but "global.import_scripts" is disabled.

• Allow everything
All forms of script execution are enabled.

Script location

• Same page
The default location where the editor searches for a script is on the wiki page, that is the current page when Ctrl-E is pressed.

• Other page
On a per page basis you can tell the editor that it also has to take scripts into account, that are located in a different wiki page, you do this by adding the [import_scripts: page name] attribute to the page. The following attribute for example:

[import_scripts: LocalScriptLibrary]

would tell the editor to also look for scripts in the wiki page "LocalScriptLibrary". If you would press Ctrl-4 you would see that the script with id "4" on that page would insert the text "--- from local library ---" at the cursor position in this page.

• Global script page
You can also define a wiki page as the global script library for the entíre wiki. You do this by specifying that page with the [global.import_scripts: page name] attribute.

Script execution

• All scripts
If Ctrl-E is pressed - and nó text is selected - then áll of these scripts are executed, in this order:

The current page
The [import_scripts: page name] page, íf specified
The [global.import_scripts: page name] page, íf specified

Per page the scripts are executed in the order they appear on the page. This behaviour is only limited by the setting of the security option: "Script security".

• One specific script
Up to six (6) scripts can be assigned to a Ctrl-number key; you do this by adding a script-id to the script block. The format for this is: <% n: ....%>, where n is a number from 1 up to 6; for example:

script 1: <% 1: editor.AddText(lib.now()) %>
script 2: <% 2: lib.addDate(editor) %>

To execute one of these scripts, press Ctrl plus it's number; so to execute script 1, press Ctrl-1 and to execute script 2, press Ctrl-2.

Pressing Ctrl plus a number will execute only the script with that number; the editor will search for the script in this order:

The current page
The [import_scripts: page name] page, íf specified
The [global.import_scripts: page name] page, íf specified

The first script with the number that is found, is executed and the editor will not search the other pages for a second (or third) script with the same number. This allows to have different scripts with the same number; the one "closest" overrules the one "furthest away".

• Editor menu
Instead of pressing Ctrl-E or Ctrl-n you can also select the appropriate option from "Editor / Evaluation" in the main menu.

Top

Custom functions

Next to the existing functions in "evalLibrary.py", you can define your own functions or change the specification of existing ones. To do so, copy the existing file:

Create the directory if it doesn't exist. Then edit the new evalLibrary.py to add your own functions. The new file will not be touched when upgrading wikidPad.

In principle you should remove all the functions from the new file, that should keep their default functionality and only maintain the functions that you want changed and new ones you create. On startup WikidPad will read both files in the order:

extensions / evalLibrary.py
user_extensions / evalLibrary.py

and override any functions in extensions/evalLibrary.py with those found in user_extensions/evalLibrary.py and add your additional custom functions.

Remarks:
• Depending on the type of the new functions, they can be used with: in-editor, insertion and script.
• Don't forget to save the file and restart wikidpad to make use of the new functions.

Top

Settings

Local attributes

• [import_scripts: page name]
Sets the page to be used as the script library for the current page.

Top

Global attributes

Scripting: see Scripts

• [global.import_scripts: page name]
Sets a default page to be used as the script library for the whole wiki; can be overruled by the local "import_scripts" attribute. The scripts in the specified page will automatically be available on every page of the wiki.

Top

Options

Application settings: Security

• Process auto-generated areas
Experimental feature, use not recommended!

• Process insertion scripts
Control if insertions with key "eval" are allowed be evaluated as Python expressions or not, see also Scripts.

• Script security
Set the security level for script execution, see also Scripts. The possible options are:

No scripts: Script execution is completely disabled. This is the default.
No import_scripts: Scripts on the currently open page can be executed and expressions evaluated. Importing scripts from other pages with the import_scripts property doesn't work (see below how to do this).
No global.import_scripts: Property "import_scripts" works, but "global.import_scripts" does not
Allow everything

Top

previous: Back
parents: GlobalAttributesScripting, Intro9Advanced, LocalScriptLibrary, WikidPadAdvanced, WpInsertions, WpOptionsSecurity
[help.status: done]