Tool:Butler

{{UnsafeScript}}
{{Infobox Tool
| author           = HonoredMule
| user             = yes
| type             = User Script
| subcategory      = User Scripts
| version          = 0.5.2
| supercedes       = HarmlessButler
| date             = 2017-03-28
| file             = 
| link             = {{SERVER}}/butler/ButlerLoader-latest.user.js ButlerLoader-latest.user.js
| link2            = {{SERVER}}/butler/latest/Butler.user.js Butler.user.js
| desc             = Upgrades the in-game UI, improves account management
| url              = 
| urlname          = 
| dep1             = Any modern browser supporting user scripts and [http://www.w3.org/TR/cors/ {{tooltip|CORS|Cross-Origin Resource Sharing}}] (not Opera until version 12)
}}
'''Butler''' is the planned sequel to [[Tool:HarmlessButler|HarmlessButler]] which was built for the original game interface.  This sequel will be much more ambitious in design, providing a greater wealth of persistent account management features and usability enhancements, an accordion-style navigation panel whose default focus "follows" the context of your current in-game view (and also displays plenty of context-sensitive concise overview information regarding both your current city and your account overall), a greatly enriched chat system, and integration with future web-based services.

Most data-heavy functionality is not yet present, but the UI/usability enhancements are very robust now.  ''New users please note: on the first install, it will often be necessary to wait a while and/or reload a few times before Butler becomes operational.''  This is a result of having to download and compile additional static and template data from the server.  Rest assured it will start working on its own, and very efficiently once that content is cached.


== Current Features ==

*Mail page controls enhanced to cycle between selecting unread, read, all, and none (instead of just all/none)
*Quick access to Arcanum Illyria from inside Illyriad using a sidebar tab
**Context menus provide quick lookups for wiki pages of players and alliances
*Links which point to the current location now reload the page's contents (instead of doing nothing)
*Better town/player/alliance context menus within Butler's UI (i.e. Butler's chat, etc.)
*Optional quick-view tooltips for the stock interface, enhancing navigation and unit icons
*Apply a user-defined default map zoom
*Automatically focus input on the most relevant input when loading a new page
**This is the first of many options controlled from a general settings pane
*Quick-folding tabbed-pane area for displaying most of Butler's present and future features while taking minimal browser screen space
**Double-row, many column tab area with auto-scrolling to selected tab, offering plenty of room for expansion
**Always-visible narrow strip for (future) minimalist event listing (as with HarmlessButler, but with more extensive context-sensitive controls...and full event listing with timers, etc. supplied as separate pane to keep the opened panel narrow)
**Special NAV-pane shows the last visited world map view or email listing
**New chat system with plenty of space, smooth operation, and good readability
***Optional per-player and/or per-alliance message highlighting based on user-defined colors
***Optional per-alliance message highlighting using automatically generated colors (when no user-defined color available)
***Default in-game chat can be "turned off" without affecting Butler's chat (messages still come).
***Chat-alert icon automatically appears when new unread alliance chat messages exist, clicking takes straight to alliance chat
***URLs automatically turned into links that open in new pages
***Emoticon text converted into images using flexible matching (currently 90 different emoticons supported)
****Popup screen from chat settings shows all emoticons available with your current version.
****Emoticons will never conflict with URLs or special character sequences (html entities)
*Every small feature user-configurable, and many of them will be opt-in rather than opt-out

== Screenshots ==

''See [[{{FULLPAGENAME}}/Screenshots]]''

== Installation Options ==

Butler is available as either a standalone userscript, a lightweight "loader" userscript, or a javascript bookmarklet.  The loader and bookmarklet versions will place the actual script directly in Illyriad's pages, and the bookmarklet can be loaded even by browsers incapable of running userscripts.

Each method has its pros and cons:
*Native will always work and gracefully degrade service-dependent features if HonoredSoft.com experiences downtime.
*Native will not work if the browser places even more security restrictions on userscripts than already exist for standard, non-privileged javascript (demerit, Chrome, for disallowing userscripts from interacting with existing script data).
*Loader will avoid wonky security issues (again, Chrome).
*Loader can either target a specific version or automatically load the latest release or development snapshot.
*Loader will not work during any HonoredSoft.com downtime (the script must be served from somewhere).
*Bookmarklet can be used by browsers which do not support userscripts in any way.
*Bookmarklet will only run on demand, not automatically.
*Bookmarklet also has all the advantages and drawbacks of the Loader.

=== Latest Version ===
*'''Preview''': <!--[{{SERVER}}/butler/preview/latest.htm view here]-->''Preview is no longer available.''
*'''Native''': {{SERVER}}/butler/latest/Butler.user.js
*'''Loader''' (current latest): {{SERVER}}/butler/latest/ButlerLoader.user.js
*'''Loader''' (auto-updating): {{SERVER}}/butler/ButlerLoader-latest.user.js
*'''Bookmarklet''' (paste into location bar, or create new bookmark with the code below as the URL)
  <nowiki>javascript:(function(){var butler=document.createElement("script");butler.type="text/javascript";butler.src="https://illyriad.honoredsoft.com/butler/latest/Butler.user.js?method=bookmarklet&target=latest";document.getElementsByTagName("head")[0].appendChild(butler);}());</nowiki>
The preview is a rough example of Butler running in an empty page, which users can explore without having to install anything or let Butler see any of their account data.  Anything relying on actual account data will be either non-interactive or completely broken.  But you can get a very rough, basic idea of what to expect.

=== Developer Snapshot ===
Players can also view a pre-release snapshot of work currently being developed using the following links:
*'''Preview''': <!--[{{SERVER}}/butler/preview/dev.htm view here]-->''Preview is currently unavailable.''
*'''Native''': {{SERVER}}/butler/dev/Butler.user.js
*'''Loader''' (current latest): {{SERVER}}/butler/dev/ButlerLoader.user.js
*'''Loader''' (auto-updating): {{SERVER}}/butler/ButlerLoader-dev.user.js
*'''Bookmarklet''' (paste into location bar, or create new bookmark with the code below as the URL)
  <nowiki>javascript:(function(){var butler=document.createElement("script");butler.type="text/javascript";butler.src="https://illyriad.honoredsoft.com/butler/dev/Butler.user.js?method=bookmarklet&target=dev";document.getElementsByTagName("head")[0].appendChild(butler);}());</nowiki>
Please note that these snapshots are highly unstable and not guaranteed to be even partially functional at any given time.  They are essentially a look at whatever garbage the author has half-written at this very moment.

=== Older Versions ===
(Loaders linked here will never auto-update)
*'''0.5.2''': [{{SERVER}}/butler/code/0.5.2/Butler.user.js Native], [{{SERVER}}/butler/code/0.5.2/ButlerLoader.user.js Loader]
*'''0.5.1''': [{{SERVER}}/butler/code/0.5.1/Butler.user.js Native], [{{SERVER}}/butler/code/0.5.1/ButlerLoader.user.js Loader]
*'''0.5.0''': [{{SERVER}}/butler/code/0.5.0/Butler.user.js Native], [{{SERVER}}/butler/code/0.5.0/ButlerLoader.user.js Loader]
*'''0.4.0''': [{{SERVER}}/butler/code/0.4.0/Butler.user.js Native], [{{SERVER}}/butler/code/0.4.0/ButlerLoader.user.js Loader]
*'''0.3.4''': [{{SERVER}}/butler/code/0.3.4/Butler.user.js Native], [{{SERVER}}/butler/code/0.3.4/ButlerLoader.user.js Loader]
*'''0.3.3''': [{{SERVER}}/butler/code/0.3.3/Butler.user.js Native], [{{SERVER}}/butler/code/0.3.3/ButlerLoader.user.js Loader]
*'''0.3.2''': [{{SERVER}}/butler/code/0.3.2/Butler.user.js Native], [{{SERVER}}/butler/code/0.3.2/ButlerLoader.user.js Loader]
*'''0.3.1''': [{{SERVER}}/butler/code/0.3.1/Butler.user.js Native], [{{SERVER}}/butler/code/0.3.1/ButlerLoader.user.js Loader]
*'''0.3.0''': [{{SERVER}}/butler/code/0.3.0/Butler.user.js Native], [{{SERVER}}/butler/code/0.3.0/ButlerLoader.user.js Loader]
*'''0.2.0''': [{{SERVER}}/butler/code/0.2.0/Butler.user.js Native], [{{SERVER}}/butler/code/0.2.0/ButlerLoader.user.js Loader]
*'''0.1.0''': [{{SERVER}}/butler/code/0.1.0/Butler.user.js Native], [{{SERVER}}/butler/code/0.1.0/ButlerLoader.user.js Loader]
*'''0.1a2''': [{{SERVER}}/butler/code/0.1a2/Butler.user.js Native], [{{SERVER}}/butler/code/0.1a2/ButlerLoader.user.js Loader]
*'''0.1a1''': [{{SERVER}}/butler/code/0.1a1/Butler.user.js Native], [{{SERVER}}/butler/code/0.1a1/ButlerLoader.user.js Loader]
Bookmarklets for older versions will not be provided, but observant readers should be able to easily figure out how to adjust the "latest" bookmarklet to target a specific version, by looking at how these links are constructed.

== Browser Compatibility Status ==

Even though Butler does not rely on any browser-specific APIs or special userscript privileges, it is still at the mercy of the various browsers' userscript implementations (if there even are any) and their capricious attitudes toward userscript "security."  The "Loader" method was initially provided in order to circumvent fickle cross-browser behavior, although it does have other benefits as well.  Before reporting bugs/problems, be sure you first check the following compatibility list and ensure you are using a combination of userscript method and browser that is expected to work.

*'''Firefox 3.6''': no longer works since version 3.6.18 (localStorage broken)
*'''Firefox 4.x+''': works perfectly with native script, loader, or bookmarklet
*'''Chrome''': cannot use native script, works perfectly with loader or bookmarklet
*'''Opera''': will work when Opera supports [http://www.w3.org/TR/cors/ {{tooltip|CORS|Cross-Origin Resource Sharing}}] (coming in version 12)
*'''Safari on Windows''': bookmarklet only (testing limited so far)
*'''Safari on Mac''': unknown (author does not have a Mac&mdash;and doesn't want one)
*'''IE8''': status unknown (author can't even get Illyriad itself to work in IE8)
*'''IE9''': status unknown (author cannot install IE9)

== Changelog ==

;2017-03-28 (0.5.2):
*Bug Fixes:
**Updated to handle Illyriad's switch to HTTPS (Note: you will need to re-install Butler by whatever method you previously used - even if it's the dynamic loader, because that needed updating as well.  You may need to install [http://honoredsoft.com/ca-honoredsoft.crt this certificate] on your browser/os as well - do this only if Butler still does not appear after re-installing)
**(Maybe) improved reliability handling initial loading of chatlog history on startup (I did this work years ago and don't remember much about it, other than it seems to work well in current state).
;2012-06-23 (0.5.1):
*Bug Fixes:
**Restored alliance and player highlighting in system messages
**Restored functionality of configuration checkboxes (was broken earlier by jQuery upgrade)
*New Features:
**Added alliance and town context menus for chat
**Display of player medals in chat now optional
**Butler chat now automatically cleaned up
***(significantly improves long-term performance)
***(at present this will disrupt precise scroll position of visible chatlogs, but it occurs very infrequently)
**When opening Butler via mouse hovering, clicking inside the panel now holds it open (particularly improves context menu behavior)
**Added "Add Friend" option to player context menu
**Friends list is now automatically and persistently sorted (first by online status then by name)
**All fonts reverted to Arial for improved readability (accepting feedback on this)
*Known Issues:
**''Firefox only''&mdash;chat alert icon doesn't disappear when revealing fully scrolled chat pane or scrolling to the bottom
***(this is FF fault for failing to raise appropriate events and will not be fixed)
**Some features of this version will be broken if updating from 0.5.0&mdash;fix by clearing static and template cache in the settings panel
;2012-06-18 (0.5.0):
*Compatibility upgrades
**Now works with Illyriad's UIv3 (released yesterday)
**Player medals are now shown in chat and in player context menus
**Improved parsing of initial chat history (more efficient and more reliable/consistent across browsers)
*New Features:
**Moved buy and sell forms to top of trade list pages
**Best input re-focused on closing Butler panel
**Drop shadows removed from stock text elements and link hover effects for improved readability
*Bug Fixes:
**Butler control panel tabs/location once again saved (was broken for several versions)
*Other:
**Codebase improvements for general context menu handling and data parsing, paving the way for replacing all stock context menus with more robust Butler-style equivalents
;2012-04-22 (0.4.0):
*Bug Fixes:
**Fixed URL rewrite to handle URLs with parameters (like market resource pages)
**Contextual input focus is now restored when closing the control panel
**Updated for compatibility with the latest Illyriad update (which now uses a much newer version of jQuery)
*New Features:
**Added simple analytical details to unit tooltips
**Added option to automatically open/close the control/chat panel on hover (defaults to off)
**Buy and sell forms moved to top of market trading pages
**Butler now remembers which tabs/panes were in view between visits to Illyriad

[[{{FULLPAGENAME}}/Changelog|Full Changelog]]