MM5 Developer (and skinning) API

To discuss development of addons / skins / customization of MediaMonkey.

Moderator: jiri

MM5 Developer (and skinning) API

Postby jiri » Fri Jun 19, 2015 7:51 am

Introduction
MediaMonkey5 is a fully HTML-based desktop application which uses Chromium for rendering. This means that the entire UI is driven by an HTML/CSS/JS stack, which is fully accessible to developers and skinners. JS in cooperation with native code drives the non-visual aspects, also fully controllable by developers. This gives unprecedented customization options to create beautiful skins, new or enhanced functionality and great addons in general.

Documentation
  • This document is intended to give you an introduction about where to start.
  • API reference is a complete reference to all the functionality provided both by MM native code and JS libraries.
  • Sample scripts and skins are a good source of how-tos. They are placed directly in 'scripts' and 'skins' folders (see below for details). Some more scripts are in the SampleScripts folder (can be installed via Tools > Extensions > [Add]).
  • Probably the most comprehensive source of information is directly within the MM source code (see the folder structure below), particularly all the JS scripts that power the UI framework. From these, you can answer most questions about individual features and study/modify behavior beyond what’s possible with the documented API.
  • If you have questions that aren’t answered by the above please raise them in the MM5 Developers Forum to be answered by MM devs or other Addon authors.
  • The current scripting API isn’t final. We expect it to evolve and improve based on developer feedback. We are really looking to you for input so that we can add to / modify / and tune the interface so that MediaMonkey5 is extensible enough to meet the large majority of developer requirements.

Folder structure
All the HTML/CSS/JS code that handles MM functionality is stored in a tree structure. As a developer, you can add new files, replace existing, or even extend functionality of the existing files. This is achieved by replication of the folder structure in Addons. For example, if a file controls\checkbox.js is present in the Addon, it completely replaces the default MM functionality of a checkbox. Similarly, an _add suffix in a filename extends functionality of an existing file. E.g. dialogs\dlgAbout_add.js can contain code that adds new controls to the layout of the About dialog.
  • Root - Contains mainly mminit.js, which has the basic MM JS routines, several other utility .js files, maincontent.html which contains the basic definition of the main window. Also important is viewHandlers.js, which defines the tree structure of MM and behaviour of the views.
    • controls - Contains all the controls used in MM UI. This starts with very basic controls, like button.js or dropdown.js, and continues with more complex things like listview.js and goes all the way to the complex UI elements, like equalizer.js, player.js or autoPlaylistEditor.js.
    • dialogs - All the dialogs reside here, e.g. dlgConvertFormat.html + dlgConvertFormat.js
    • layouts - Subfolders contain individual layouts, i.e. something that can replace/modify the files in the default folder structure in order to achieve completely different layout of MM (e.g. "Touch mode" layout). Unlike skins, layouts are supposed to mainly modify dimensions, positions and types of UI elements, not their color, etc.
    • scripts - There are some sample scripts included demonstrating various aspects of MM customization. Some more are in the SampleScripts folder.
    • skin - Contains basic skin definitions, mostly a set of LESS files (an extension to CSS).
      • icon - Contains all the icons used by MM. They are in SVG format in order to scale nicely to any display resolution. As anything else, they can be easily replaced by any Addon (skin or script).
    • skins -  Subfolders contain individual skins, i.e. something that can replace/modify the files in the default folder structure in order to achieve completely different looks of MM. Unlike layouts, this is supposed to mainly modify colors, fonts, icons, etc.

Scripts
Scripts should be placed in the Scripts folder, either as a new subfolder or as a single zip file. They should follow the folder structure described above in order to modify/replace existing functionality of any part of MM. In script you can use localRequirejs when you need to include script file from the script package.

Skins/Layouts
Skins and Layouts should be placed in the Skins and Layouts folders, either as a new subfolder or as a single zip file. The idea of separation of skins and layouts is that layout defines how it works while skin more or less defines how it looks. Skins consist of a set of LESS (see http://lesscss.org/ for documentation) files that are later automatically compiled into a single CSS that drives the look of the application. The most important files are:
  • skin_complete.less - Links all the other skin files - usually not modified by skinners.
  • skin_base.less - Basic constants, like colors, margins, etc. - almost always modified by skinners.
  • skin_layout.less - The part of CSS that we use for basic layout of our windows, i.e. something that will almost never be modified by skinners.
  • skin_{control_name}.less - Specific CSS for given control, e.g. its borders (whether they are rounded, etc.)
  • skin_custom.less - Included as the last, so that skinners can re-define anything, add some specific CSS, etc.

Cross platform considerations
The framework is designed to be ready for deployment on any platform, since the HTML/CSS/JS code is platform independent. Some UI details can certainly be tweaked so that it looks native to a particular platform.

Pre-MM5 scripts, skins and plugins
  • MM4 scripts are mostly VBS-based and specific to the Windows platform.  During the planning phase of MM5, we decided to make a clean break from this so that MM5 scripts could be cross-platform and more powerful. As a consequence, MM5 has a completely different interface from that of MM4, and support for MM4 scripts in MM5 would be very hard to implement. That said, we are open to any suggestion from developers re. how to simplify porting of MM4 addons…
  • MM4 skins are so different from when MM5 offers that we don’t even consider any backward compatibility. Just consider MM4 bitmaps vs. MM5 vector based graphics (SVG icons, …), new interface elements in MM5, etc.
  • Winamp visualization plugins is replaced by JS framework, i.e. fully crossplatform now.
  • Winamp general plugins won’t be needed anymore, since JS scripting should be able to achieve the same (and more) in a more cross-platform fashion.
  • Winamp input / output / DSP plugins are presently supported in Windows builds, though we’re evaluating our options re. how to support such functionality cross-platform.

Tips & tricks
  • We currently use Chromium version 53, but will keep it updated as much as possible. Chromium version can help you to decide which HTML/CSS/JS features can be used (e.g. at http://www.chromestatus.com/features or http://caniuse.com/).
  • The debug version of MM5 contains tools to look under the cover and debug JS scripts or HTML/CSS layouts. One option is to use Ctrl+Alt+Shift hotkey to show Chromium Developer Tools. Another option is to right-click anywhere in the UI, where the last two items give you direct access to the Developer Tools, including Inspect Element feature.
  • Naming conventions: We follow this naming convention http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml?showone=Naming#Naming and suggest all the scripts do the same.
jiri
 
Posts: 5290
Joined: Tue Aug 14, 2001 7:00 pm
Location: Czech Republic

Re: MM5 Developer API

Postby jiri » Mon Jun 22, 2015 3:04 am

I locked this post, please continue discussion in individual threads.

Thanks,
Jiri
jiri
 
Posts: 5290
Joined: Tue Aug 14, 2001 7:00 pm
Location: Czech Republic


Return to MediaMonkey 5 developer forum

Who is online

Users browsing this forum: No registered users and 1 guest