User Customization (#596)

* first version: file icon replacement

* new test: disabling extensions

* massive folder & files restructuration

* vscode module abstracted from settings.

* simplifying utils folder

* fixed issue with custom path

* temporary hack as vscode doesn't allow absolute paths in icon css

* remove dot property from IFolderExtension

* folder merging enabled

* removing not needed functionality

* tests for presets

* line added to the end of the document

* commands added to the contribution node

* commands scaffolding

* Preparing code for IconGenerator refactoring

* path use simplified. path injection allowed.

* presets working ok!

* cool messages added

* readme links fixed

* iconGenerator tests refactored

* settings and readme update

* First readme draft

* readme update

* readme update

* small readme fix

* Fix readme grammar

* css inside ``

* fixed path

* added supported icon extension list

* supported extensions link added to readme

* iconPath are now generated using Unix style regardless of being built in a Windows machine.

* barrel support for models

* readme update

* testing support samples reduced for mantainability's sake.

* merger module moved to icon-manifest folder

* preparing default icons to be ready for customization.

* Fixing Unix case sensivity issues.

* Forgot to push the file...

* renaming files for consistency sake

* more naming standarization

* getting rid of isGt160

* special renamed to default for consistency's sake

* Build process is working with the new setup and tests are all passing.

* default merging

* getting rid of defaultExtensionTypes

* custom flag added for custom defaults

* support for disabling default icons

* New tests and fixes

* more tests and small fixes.

* default icons are also using icon suffix

* making the contribution points more user friendly

* new hide folders preset added and tested.

* Readme reviewed

* readme update

* renaming parameter to avoid shadowing

* removed comment

* Now using ng_ convention for angular 2 preset.
Renamed to angular to follow AngularJS team directives about naming.

* Suport for ts defs official icon

* getting rid of iconSuffix parameter as per JimiC suggestion

* no need to create a folder in extensions folder anymore.

* no need for absolute paths anymore

* Small fixes

* using .posix to use unix join method

* readme updated with the correct os x path

* ignoring mac files

* empty line for gitignore

* Package.json modifying moved to build process only.

* general fixes

* ignoring example for the extension deployment

* some more fixes

* posix not working for relative

* removed space from vscodepath function

* making tslint happy

* space allowed before parens in anonymous functions

.gitignore

@@ -2,4 +2,5 @@ node_modules
 out
 examples
 npm-debug.log
-.vscode-test/**
+.vscode-test/**
+.DS_Store

.vscode/launch.json

@@ -18,11 +18,17 @@
             "type": "extensionHost",
             "request": "launch",
             "runtimeExecutable": "${execPath}",
-            "args": ["--extensionDevelopmentPath=${workspaceRoot}", "--extensionTestsPath=${workspaceRoot}/out/test" ],
+            "args": [
+                "--extensionDevelopmentPath=${workspaceRoot}",
+                "--extensionTestsPath=${workspaceRoot}/out/test"
+            ],
             "stopOnEntry": false,
             "sourceMaps": true,
-            "outFiles": [ "${workspaceRoot}/out/test/**/*.js", "${workspaceRoot}/out/src/**/*.js" ],
+            "outFiles": [ 
+                "${workspaceRoot}/out/test/**/*.js",
+                "${workspaceRoot}/out/src/**/*.js"
+            ],
             "preLaunchTask": "npm"
         }
     ]
-}
+}

.vscodeignore

@@ -4,9 +4,8 @@
 test/**
 src/**
 **/*.map
-out/src/build-tools/**
-out/src/models/**
 out/test/**
+out/src/example/**
 typings/**
 examples/**
 images/*.psd

README.md

@@ -19,37 +19,19 @@ I would also like to thank the whole community for their support: bringing in id
 
 ### State of the extension
 
-**With the release of 4.0.0 version, support for old functionality has completely been removed for VSCode**.
+**Release 5.0.0 introduces the ability for users to customize the icons without having to inject anything into the `Visual Studio Code's code`.** 
 
-#### Why is this happening?
+This is a huge step again to allow the users to fully customize how the icons look like and how they can be associated to any extension at will.
 
-There are several motives that have led me to take this decision:
+`Custom Icon associations` is still not supported by `VSCode API` but we thought that it was a very demanded feature and thought of a way to make it work for you. Remember that there's still an [open issue in VSCode's repo](https://github.com/Microsoft/vscode/issues/12493#issuecomment-249117649) talking about how they could provide official support for this feature. Provide a +1 if you want the VSCode team to support it. More information in [#328](https://github.com/robertohuertasm/vscode-icons/issues/328).
 
-1. The main goal of this extension has been completely achieved, which was to point out the importance of having icons in VSCode.
-2. VSCode 1.6.0 supports icons beyond the file explorer. [See vscode#11751](https://github.com/Microsoft/vscode/issues/11751#issuecomment-248634495) 
-3. Code Injection has its drawbacks both for the VSCode team and for me. Having to keep up with the Insiders build has become a nightmare and from time to time new recurrent issues are being created in VSCode's Github project about something being broken.
-4. Code injection will be eventually not allowed.
-5. Support from VSCode team is great and they're willing to hear all the suggestions from the community regarding icon themes.
+**Thank you all for your kind support. We will continue to try to improve the extension to make it more user friendly :D**
 
-Still, there's one missing point: `Custom Icon associations` is still not supported. They're not convinced of the value that this would bring to VSCode, so again, it's up to all of us to make the difference. I suggest that you create a Github issue with your opinions on this matter, so that the VSCode team can have a clear vision about importance of `Custom Icon associations` to the community (us). [This is a starting point](https://github.com/Microsoft/vscode/issues/12493#issuecomment-249117649). Provide a +1 if you want the VSCode team to support this feature.
-
-More information in [#328](https://github.com/robertohuertasm/vscode-icons/issues/328)
-
-Finally, I also would like to ask you to raise the possible issues that you may find while using this extension into the [extension's repository](https://github.com/robertohuertasm/vscode-icons/issues), not the VSCode one ;D
-
-**Thank you all for your kind support. Finally icons are here to stay (that was the main purpose of this extension). Now let's hope they get even better :D**
-
-## Christmas release
-@JimiC has been working hard and has built some **very cool folder icons** for this Christmas! Besides that, he has also transformed a **huge quantity of our `png icons` into nicer `svg icons`**.
-
-As you may have notice we did a **regresion regarding `js and ts` icons**. Some of you were not happy with the official logos so we decided to keep the old ones until we can provide with the ability to customize some of the icons. 
-
-You may know that the `VSCode API` is not really very flexible, but the team has been thinking on a few ways to make the **icon customization** possible without tampering the original VSCode code.
-
-Please, stay tuned, because we may deliver a first version of this feature soon.
+----
+## New Year release
+We're happy to annouce that the extension now **provides custom icons and some icon presets** like `Angular`, `Official JS Logo`, `Official TS Logo` and `Hide Folders`. With this release you will be able to completely tune the way the icons look! Please, take a look at the corresponding section to know more about how to make this work.
 
-Thank you all for your support!
-Merry Christmas!
+Besides that, [@JimiC](https;//github.com/JimiC) along with [@ginfuru](https://github.com/ginfuru) are continuing to contribute to the massive `svg` icon conversion and providing new quality icons.
 
 ----
 ## Main Contributors
@@ -88,12 +70,134 @@ Go to **File > Preferences > File Icon Theme > VSCode Icons**.
 
 
 ## List of supported icons
-The list is slowly growing. If you want to check what icons are currently supported take a look [here](https://github.com/robertohuertasm/vscode-icons/blob/master/src/build-tools/supportedExtensions.ts). If you feel that there's some icon missing please let me know through [the issues section of the Github's repo](https://github.com/robertohuertasm/vscode-icons/issues).
+The list is slowly growing. If you want to check what icons are currently supported take a look [here](https://github.com/robertohuertasm/vscode-icons/blob/master/src/icon-manifest/supportedExtensions.ts). If you feel that there's some icon missing please let me know through [the issues section of the Github's repo](https://github.com/robertohuertasm/vscode-icons/issues).
 
 If you're a designer and you're willing to collaborate by showing your icons to the world you're more than welcome!! Currently, we don't have icons for the light template, so any help will be really appreciated and credit will be given to you ;D
 
 ## List of supported folder icons
-If you want to check which folder icons are currently supported take a look [here](https://github.com/robertohuertasm/vscode-icons/blob/master/src/build-tools/supportedFolders.ts). As usual, if you want to add an icon submit a PR or [raise a Github issue](https://github.com/robertohuertasm/vscode-icons/issues).
+If you want to check which folder icons are currently supported take a look [here](https://github.com/robertohuertasm/vscode-icons/blob/master/src/icon-manifest/supportedFolders.ts). As usual, if you want to add an icon submit a PR or [raise a Github issue](https://github.com/robertohuertasm/vscode-icons/issues).
+
+## Customizing the extension
+The extension gives you the ability to change how the icons look or even what icons are associated to each extension.
+
+We have exposed the internal API that we are using to build the `icon manifest` so you can also use it in your `vscode settings` and generate it at runtime. This will allow you to customize all the icons, add new ones and so on.
+
+Although you now have this power, we're encouraging everyone to raise an issue in [the issues section of the Github's repo](https://github.com/robertohuertasm/vscode-icons/issues) in case you find any of your customizations valuable to the rest of the community so we can implement them out of the box.
+
+But, how does this work?
+
+The extension now provides some specific commands for you to use. Let's talk first about the `presets` and then we're going to talk about how you can fine tune the extension.
+
+### Presets
+You have 4 different presets at the moment:
+
+- `vsicons.presets.angular` (true by default)
+- `vsicons.presets.jsOfficial` (false by default)
+- `vsicons.presets.tsOfficial` (false by default)
+- `vsicons.presets.hideFolders` (false by default)
+
+These 4 different presets can be changed manually by using a `settings.json` file inside your project's `.vscode` folder or by changing `vscode user settings`. Take into account that the place where you set these presets, or for that matter, any configuration, will be very important. `User settings` are global so all your projects will be affected by them while `workspace's settings` are specific to the project and you will be able to switch presets by project. This can be interesting for the `angular` preset, for example.
+
+These presets can also be automatically set by leveraging a new set of commands that can be found by pressing `F1` and then writing down `icons`. You will be presented with some new commands:
+
+- `Toggle Angular Preset (Workspace Level)`: This command will enable/disable the `Angular icons`.
+- `Toggle Official JS Preset (User Level)`: This command will enable/disable the `Official JS icon`.
+- `Toggle Official TS Preset (User Level)`: This command will enable/disable the `Official TS icon`.
+- `Toggle Folder Icons Visibility (User Level)`: This command will enable/disable the `Visibility of the folder icons`.
+
+Note that some of the `preset commands` will modify your `settings` at a different level. If you choose to modify them manually then you can also choose what `setting` are you going to use.
+
+It's also important to say that if you choose to make a manual modification you will have to execute the `Apply Icons Customization` command *(see below)*.
+
+The `Angular Preset` will affect all icons beginning with `ng_` so you'd better name your custom icons accordingly if you want it to work flawlessly. ;P
+
+### Fine tuning
+Along with the commands we introduced before you will find two more (just press `F1` and type `icons`):
+
+- `Apply Icons Customization`: This command will regenerate the `Icons manifest` with your customizations and restart the IDE for the changes to take effect.
+- `Restore Default Icon Manifest`: This command will revert any changes you may have applied and restore the extension to its default state.
+
+But before you can even use them you will have to go to your `settings` and make your magic. The settings will provide you 2 different `array items`:
+
+- `vsicons.associations.files`: [IFileExtension[]](https://github.com/robertohuertasm/vscode-icons/blob/master/src/models/extensions/fileExtension.ts)
+- `vsicons.associations.folders`: [IFolderExtension[]](https://github.com/robertohuertasm/vscode-icons/blob/master/src/models/extensions/folderExtension.ts)
+
+Each item of the array represents a file or a folder icon. The functionality is the same for `files` and `folders`.
+
+Note that it's important to know what the current [supported file extensions / icons](https://github.com/robertohuertasm/vscode-icons/blob/master/src/icon-manifest/supportedExtensions.ts) and [supported folder extensions / icons](https://github.com/robertohuertasm/vscode-icons/blob/master/src/icon-manifest/supportedFolders.ts) are.
+
+Along with the previous arrays you will have 4 more settings available that will help you customize how the default icons for files and folders look like:
+
+- `vsicons.associations.fileDefault.file`: [IDefaultExtension](https://github.com/robertohuertasm/vscode-icons/blob/master/src/models/extensions/defaultExtension.ts)
+- `vsicons.associations.fileDefault.file_light`: [IDefaultExtension](https://github.com/robertohuertasm/vscode-icons/blob/master/src/models/extensions/defaultExtension.ts)
+- `vsicons.associations.fileDefault.folder`: [IDefaultExtension](https://github.com/robertohuertasm/vscode-icons/blob/master/src/models/extensions/defaultExtension.ts)
+- `vsicons.associations.fileDefault.folder_light`: [IDefaultExtension](https://github.com/robertohuertasm/vscode-icons/blob/master/src/models/extensions/defaultExtension.ts)
+
+```json
+// this is a very simple interface.
+// your configuration will simply replace the default icon. See Custom Icons sections below.
+"vsicons.associations.fileDefault.file": { "icon": "myfile", "format": "svg" },
+// if you want to disable default icons for folders that will do the trick
+"vsicons.associations.folderDefault.folder": { "icon": "myfile", "format": "svg", "disabled": true }
+```
+
+####  Some examples
+```json
+// Adding new extensions to an already supported icon.
+// note: the format must match the existing one. If not, it will use the extension you provide.
+"vsicons.associations.files": [
+  { "icon": "js", "extensions": ["myExt1", "myExt2.custom.js"], "format": "svg" }
+]
+
+// Disabling an already supported icon.
+// note: this is, indeed, the functionality that presets are leveraging.
+"vsicons.associations.files": [
+  { "icon": "js", "extensions": [], "format": "svg", "disable": true }
+]
+
+// Adding a new extension.
+// note: see instructions below on custom icons.
+"vsicons.associations.files": [
+  { "icon": "custom", "extensions": ["custom", "my.custom"], "format": "svg" }
+]
+
+// Changing the icon to an already supported icon.
+"vsicons.associations.files": [
+  { "icon": "newIcon", "extensions": [""], "format": "svg", "extends": "js" }
+]
+
+// Overriding an already supported icon.
+// note: the difference between overrides and extends is that overrides will completely
+// remove the older icon functionality while extends will keep older settings by 
+// putting yours on top.
+"vsicons.associations.files": [
+  { "icon": "myJs", "extensions": ["js", "custom.js"], "format": "svg", "overrides": "js" }
+]
+
+```
+
+#### Custom Icons
+In order to place your custom icons you will have to create a specific folder. Depending on your OS the path will be:
+
+- Windows: `C:\Users\<your_user>\AppData\Roaming\<Code Folder>\User\vsicons-custom-icons`
+- Linux: `/home/<your_user>/.config/<Code Folder>/User/vsicons-custom-icons`
+- Mac: `/Users/<your_user>/Library/Application Support/<Code Folder>/User/vsicons-custom-icons`
+
+`<Code Folder>` refers to the name of the folder of VSCode depending on the version:
+```
+- `Code` for the stable version.
+- `Code - Insiders` for the insiders version.
+```
+
+Once you have created the folder you can put all your custom icons there. But, again, they have to follow `vscode-icons` naming conventions:
+
+- Files: `file_type_<value_of_icon_property>@2x.svg`
+- Folders: `folder_type_<value_of_icon_property>@2x.svg` & `folder_type_<value_of_icon_property>_opened@2x.svg`
+- Default Files & Folders: `default_<value_of_icon_property>@2x.svg`
+
+**Note that folders must have two icons!!**
+
+See [here the supported icon extensions]((https://github.com/robertohuertasm/vscode-icons/blob/master/src/models/extensions/fileFormat.ts)).
 
 ## Contributing with icons