View source

==The Basic Concept==
To customize a website you need to create a Script. A Script is nothing you have to write on your own. Think of a Script as a set of data which contains all information about your customization. The most important data a Script contains are:
*Name: You can give the script a name to find it easier if you want to modify it.
*List of URL patterns for which the script should apply
*List of URL patterns for which the script should '''not''' apply (overrules the include patterns)
*List of actions (in fact it is a tree) which are executed every time the page is loaded or modified.

Each action modifies the site in a specific way, e.g. removes an element, adds a shortcut etc.

When a website is loaded CYW looks up on the basis of the URL patterns which scripts should be applied and executes the actions contained in each matching script.
The script is re-executed if the site is changed via JavaScript to support dynamic websites like Gmail or Facebook (this can be turned of via a script parameter).

==Creating a Script==
To create a script you just have to press F10 or click on the CYW statusbar icon. The sidebar openes and the Edit Script window will appear in it. 
If you haven't created a script for this website yet, the menulist at the top of the sidebar window will only contain the entry "New script", which will be already selected.

When you now move the mouse over the website you will see frames moveing around indicating the currently selected element. Most of the actions refers to one specific element on the page. I call such an element a target element. To add an action for an element just click on it and a popup menu will appear showing all possible actions. Select the action you want and after editing the action specific parameters in a dialog the action will be added to the actions tree in the sidebar. To select an action you can also use shortcuts which are displayed behind every action item in the context menu. To show an overview of all available shortcuts press F1 while editing the scipt.

Sometimes it is difficult to select the right element with the mouse. Therefore I added some shortcuts to enable selection also via the keyboard:
* Arrow-Down/Right moves the selection to the next sibling of the current element.
* Arrow-Up/Left moves the selection to the previous sibling of the current element.
* Ctrl+Arrow-Down moves the selection to the first child of the current element.
* Ctrl+Arrow-Up moves the selection to the parent of the current element.

All changes of the website (e.g. removal or rearrangement of elements) are instantly displayed, so you have a full WYSIWYG (What you see is what you get) mode. Undo of editings is also supported via the standard Ctrl+z.

At the lastest after adding the first action the include pattern listbox is automatically filled with one entry. CYW takes the full URL of the website (or frame) you edit as the best guess. URL parameters (all the stuff behind a '?') will be replaced by a wildcard character '*'. Nevertheless you should check if the proposed pattern is the correct one. To edit the pattern just double click it. On the second pane of the sidebar window you'll also find a listbox to specify URL patterns for which the script should not apply. The exclude patterns overrule the include patterns.
After pressing the Save button the sidebar is closed, the page is reloaded and the script applied. Please note that if you reload a page manually while editing it no scripts will be applied.

==Editing an Existing Script==
To edit an existing script just go to the website which you used for creating the script and switch to the edit mode by pressing F10 (or clicking the icon). All matching scripts will appear in the menulist at the top of the sidebar window. Select the one you want to edit and it's data will be filled into the sidebar window. You can now edit actions as you like.
You sometimes will wonder why your script doesn't appear in the menulist. The reason for that is simple: The current URL doesn't match to the pattern you've provided while creating the script. In this case press the select button and select your script from the dialog. The website will be shadowed as the URL pattern of your script doesn't match the current URL. Edit the existing patterns or add a new one either via the context menu of the listbox or by pressing the "Add" key if the focus is within the listbox. At the end the part of the website for which the script should apply must be unshadowed. 

== Define the Target Element of an Action==
Almost every action refers to '''one''' element on the website. These kind of actions are called Targeted Actions. One fundamental problem of CYW is to find a correct description of the target element so CYW can find it again after every page load. In the context of CYW such a description is called a Target Definition. CYW supports two styles to create the Target Definition: the so-called Simple Style and with a XPath expression.
The Simple Style consist of a list of name/value pairs, where the frist name/value pair defines the tag (e.g. tag=INPUT) and the subsequent ones defines values of the attributes of the target element (e.g. name=searchField form=mainform). If the attribute definitions are not sufficient to clearly define the element the last name/value pair defines the position of the element within the remaining elements (e.g. pos=2). The Simple Style is the default for all form elments and links.

As a second way to define the target element you can use a XPath expression. A tutorial about XPath can be found under [http://www.w3schools.com/Xpath/|http://www.w3schools.com/Xpath/], the XPath specification can be found under [http://www.w3.org/TR/xpath|http://www.w3.org/TR/xpath].

In either case CYW gives you instantly visual feedback to which element(s) the current defintion refers. For the simple style there is also a code completion available containing all attribute values of the selected element. If the keyboard focus is within the field for the target definition you can activate the code completion menu with "Ctrl+Space".

==The Actions List/Tree==
In the first point I stated a Script contains a list of actions. That's a little bit imprecise as in fact it is a tree of actions. I.e. some actions could contain other actions. These actions are called Containter Actions. Actions within a Container Action are only executed under certain conditions. To add an action to a container action you have to select the container action in the actions tree. Actions which are '''not''' contained  within another action are always executed.

==Types of Actions==
The following list gives an overview about all available actions and their effects. In the parentheses behind the name is denoted whether it is a Targeted Action (TA) and/or a Container Action (CA).
*Click (TA)<br>Simulates a click on an element.
*Focus (TA)<br>Focuses an element.
*Modfiy (TA)<br>Modifies an element in specifc way, e.g. changes the value, color, size etc.
*Remove (TA)<br>Removes an element permanently from the website.
*Shortcut (TA)<br>Creates a keyboard shortcut for any clickable or focusable element.
*Marcro Shortcut(CA)<br>Creates a keyboard shortcut to execute the actions contained in the macro shortcut action. 
*Listview (TA)<br>Makes a list of elements keyboard navigateable. You have to select the parent element of the elements for which you want to have a listview. With Arrow-Down/Up or J/K you can move up and down in the list. Pressing "Enter" opens the first link within the current list element in the current tab, "Ctrl+Enter" openes it in a new tab (you can change that in the listview editing dialog). Pressing "Space" toggles the state of the first checkbox within the current listview element.
*Toggle Visibility Shortcut (TA)<br>Creates a keyboard shortcut to toggle the visibility of an element on/off.
*Insert HTML (TA)<br>Inserts some HTML code into the website.
*Insert JavaScript <br>Inserts some JavaScript code into the website.
*Copy (TA)<br>Copies the selected element into a CYW specific clipboard.
*Cut (TA)<br>Removes the selected element from the website and puts it into the CYW specific clipboard.
*Paste (TA)<br>Pastes the content of the CYW specific cliboard relative to the selected element (before, after, as first/last child)
*If Element Exists (TA, CA) <br>Executes the contained actions only if the selected element exists. This action is only for highly dynamic websites like Gmail. 

==Control of Re-Execution of Scripts and Actions==
More and more websites (e.g. Gmail, Facebook) uses JavaScript to change the user interface on the fly. This necessitates control over re-execution of Scripts and Actions. 
By default a script is re-executed every time an element is added to or removed via JavaScript. This re-execution can be deactivated on the second pane of the sidebar window.
This behavior can also be defined on the action level within their edit dialogs (this is not relevant for all action types). The default behavior on the type of action.