# User Interface
# Main Window
- Source Editor: Write code here. Read Editing documentation.
- Web Preview: Live HTML preview. Read Previewing documentation.
- Developer Tools: Inspect elements, view the console logs, see network requests, etc. Read Developer Tools documentation.
- Inspector: Configure the document. Read Inspector documentation.
- Toolbar: Quick access to common functions and configurability. Read Toolbar documentation.
# Split Positioning
The split between the Source Editor and Web Preview can be changed by grabbing the divider and dragging.
Double-clicking the divider (or pressing Command-Shift-Backslash) will change from a Widescreen Layout to a Portrait Layout with the Web Preview placed below the Source Editor.
The toolbar's view item or the View menu can also configure which elements are shown.
# Web Preview in Separate Window
You can tear off the Web Preview and display it in a secondary window by choosing the View > Detach Web Preview menu item. This is especially useful if you are using multiple displays and want one display to show the Source Editor and the other to have the Web Preview.
# Saving Window Settings
Whisk will save all window layout and options related to your document. Because web files (like HTML, PHP, CSS, etc.) are text only and do not contain metadata, Whisk maintains its own database of your document settings that are tied to the file path of the document.
- If you wish to make all new documents use the current document settings, you can set this via the View > Save Window Layout and Settings menu item.
- Likewise you can apply the stored settings to the current document via the View > Apply Saved Window Layout and Settings menu item.
- To reset what is saved to Whisk's default, choose the View > Restore Default Window Layout and Settings menu item.
- Outdent & Indent: Increases or decreases leading whitespace for selected lines the Source Editor. By default it will use tabs.
- Title: Shows document name and editing status. Click to modify the name or command-click the title to reveal the path.
- Zoom: Magnifies or minifies the Web Preview. To change Source Editor text size, see the Interface Preferences.
- Reload: Reloads the Web Preview.
- Preview: Clicking the primary icon will open that browser and preview to it. The drop down will show a list of browsers to preview in. For more information, read the Previewing chapter.
- Scroll Sync: This will lock the scroll for the Source Editor and the Web Preview together, so that the proportionate amount is scrolled the same in both. It is most useful for mostly text documents where the mapping of HTML code to output can be easily correlated. More complex layouts or code can produce unpredictable results.
- View: Toggle visibility of specific views in the main window. From left to right: Source Editor, Web Preview, Developer Tools, Inspector. If the current editing mode is PHP, the Web Preview control can be pressed and held to reveal a menu to choose between showing the Rendered Web Page and HTML Source Code.
# Tab Bar
On macOS 10.14 and later, Whisk supports using the macOS document tab bar to open several documents within the same window. This can be accessed via the View > Show Tab Bar menu item. It will also show up if the System Preferences' Dock Pref Pane's "Prefer tabs when opening documents" setting is "Always."
# File Inspector
This inspector can be triggered by hitting Command-1.
# Text Handling
The Encoding setting represents the character set that will be used to write the file. If the document has been previously saved, then it will also open using the selected encoding. Otherwise it will attempt to open using the Save encoding setting from the General Preferences. If this encoding does not work, it will attempt to autodetect the text encoding, and then will set this as the value.
For more in depth information, please read the section on Text Encodings.
# Style Sheet
This allows you to choose a CSS Style Sheet which will apply to the HTML code. Please see the Style Sheets chapter for in depth information about this feature.
# Watched Files
Watched Files will list all files that will automatically trigger a reload of the web preview. The list contains those that are detected through load mechanisms as well as manually added files. Please see the Watched Files chapter for in depth information about this feature.
# Tools Inspector
This inspector can be shown by hitting Command-2.
The Options area contains general settings related to what type of document you are working with and how often it should be reloaded.
- HTML: Any text in the Source Editor will be rendered as-is in the Web Preview. By default the refresh is set to Instantly.
- PHP: Text entered in the Source Editor is intended to be PHP code. It is run through the binary path specified in the General Preferences. By default the refresh is set to Instantly.
- CSS: Text entered in the Source Editor has no rendering in the Web View, therefore refreshing is disabled.
- None: There is no syntax highlighting. Text entered in the Source Editor has no rendering in the Web View, therefore refreshing is disabled.
Syntax Highlighting determines whether the Source Editor colors the text. Actual colors can be configured in the Interface Preferences.
If you have a very large document, turning off Syntax Highlighting can improve editing performance.
There are three different Refresh timings:
- Instantly: The Web Preview is refreshed immediately after every keystroke/text change.
- Delayed: The Web Preview is refreshed after a duration from the last keystroke/text change. This uses the values of the slider located on the left, where each tick mark represents one second. A delayed refresh is useful to avoid a certain amount of distraction while working but still wanting to be able to quickly see the effects of your changes. It may also be useful in situations where the Web Preview uses a lot of system resources to render and is hindering editing responsiveness.
- Manually: The Web Preview is only refreshed when hitting the Reload button or Command-R. This is useful when the content may have adverse side effects in an intermediate representation (like PHP writing to the filesystem) or from network requests.
# Code Snippets
These are bits of code that can be easily inserted to the working document by double-clicking or using custom keyboard modifiers.
Whisk opens documents with an empty page, but the "Default Page" code snippet, triggered via Command-Shift-D, is a good starting point for new documents.
Read the Code Snippets chapter of the documentation for more information.
# Color Swatches
Color Swatches provide quick access to your most commonly used colors. They are globally saved so all documents have access to them.
Read the Color Swatches chapter of the documentation for more information.
# Validation Inspector
The Validation Inspector provides a list of issues and errors in your document. You can do single validation report via the Validate page, or constantly update the issue list by switching on the Live validation checkbox.
Read the Validation chapter of the documentation for more information.
# General Preferences
- Notify when new updates are available: If checked, on startup Whisk will always look for new updates on launch. It is recommended to have this setting checked, otherwise you may be missing critical updates that include bug fixes or new features. (This option is only shown on the Tumult Store version of Whisk. The Mac App Store version uses the App Store updating mechanisms which can be configured through the System Preferences)
- Only show recommended browsers in preview menu: Whisk maintains a whitelist of browsers to show in the preview toolbar menu item because querying macOS for applications which can handle "http" URLs or "html" files can often result in non-browsers showing up in the list. However new browsers may come out which are not immediately on Whisk's whitelist or there may be applications you want to preview to which Whisk would not consider a traditional browser. If this is the case, check this box for the preview menu to show all options available on the system.
- Create new Untitled documents automatically: When checked, Whisk will create an Untitled document if it is activated without any other documents open.
# Text File Handling
Read the Text Encodings section for information about the Open and Save encoding settings.
New line endings determines which type of control character marks the end of lines. It is only used when a newline is created through editing in Whisk; existing line endings are not changed. A "newline" is an invisible character which instructs the computer to start a new line of text. In the early days of computing, DOS, Mac, and UNIX all had different invisible characters/sequences that they used. This setting is for more historic purposes, and generally should not be modified.
Path to binary indicates the command line binary that should be called when rendering PHP code. This defaults to the macOS installation location, but can be modified if you install via homebrew, MAMP, or other means. For more information, read the PHP documentation chapter.
# Interface Preferences
- User interface theme: Whisk can run in light or dark themes. On macOS 10.14 and later, a "System" option is available that uses the respective theme depending on the setting chosen in the System Preferences General Pref Pane.
- Use system accent color: On macOS 10.14 and later, an accent color can be chosen in the System Preferences General Pref Pane. This is used for certain highlights in Whisk, but may not always be desired.
- Colors: These change the syntax highlighting as well as text, background, and line highlight colors. Each is tied to a theme, so you can have independent colors on the Dark and Light themes.
- Source editor font: Changes the font and size for all documents. If a document is open, you can see the changes live.
- Line spacing: Changes the distance between lines for all documents. If a document is open, you can see the changes live.
- Highlight current line: Lightly colors the background behind the line that has the text cursor. If there is a selection, this is temporarily not drawn in lieu of the selection. The color can be configured via the "Line Highlight" color above.
- Show line numbers in gutter: This will show a number next to each line in the Source Editor. Disabling can sometimes improve performance on large files.
- Preserve indentation: If this setting is checked, the leading whitespace (spaces, tabs) of the previous line will be created as the leading whitespace for a new line.
- Wrap lines: Determines if lines that are wider than the view of the Source Editor should be displayed below, or if unchecked, cause a horizontal scrollbar to appear.
- Show invisible characters: With this checked, the Source Editor will lightly print any characters that represent whitespace or normally non-printed characters in the file. It is useful for finding "gremlins" which might be unexpected data in a file.
# Devices Preferences
Whisk can preview your document to iOS devices using the Hype Reflect application. Devices are chosen via the Preview toolbar menu item.
After a device is previewed to, it will stay in the Preview menu, even when the Hype Reflect application is not running. Clear Recently Previewed Devices will reset these choices, so it will then only show active devices.
# File Access Preferences
The Preference Pane will only show up on the Mac App Store version of Whisk. For more information, see the App Sandboxing chapter of the documentation.