Documentation

[PitPik]

There has to be more documentation for the API and usage for developers and end-users.

[paul-cheung]

where is API documentation???

[Abdillah]

Yes, and I think the demo is likely a complex usage of this.

[mrloop]

I think the libraries would get more usage if there were some clearer demos and descriptions about the usage.

[oojacoboo]

Docs are not good at all. I've just spent a ton of time to try and get this going based on examples I've seen, but I can't even find the corresponding js in the examples and the API docs are missing.

Oh well - going to have to try something else :/

[PitPik]

Hi @oojacoboo what do you need? Have you seen http://www.dematte.at/cpn/javaScript_implementation/ or http://www.dematte.at/cpn/jQuery_implementation/? The properties, methods and callbacks are described on https://github.com/PitPik/colorPicker and the same things for the implementations you find on https://github.com/PitPik/colorPicker/tree/master/jQuery_implementation or on https://github.com/PitPik/colorPicker/tree/master/javascript_implementation for vanilla js. Most Properties explain themselves by its name (if they are not properly commented) and otherwise you might find out by a little experimenting. If you are at the demo page (http://www.dematte.at/colorPicker/) and type 'myColor' into the console, you'll see the color model and its methods, if you change the dropdown in the demo from 'Colors' to 'ColorPicker' you'll get the colorPickers model in the console (by typing 'myColor'). The model is very clean and great for inspecting. No private variables or methods, just things that colorPicker really uses. All of those properties and methods are documented on the main gitHub site of colorPicker.

I'm willing to help out if you tell me what you want / need. Thanks though for being interested in colorPicker. Cheers Peter

P.S.: I'm a 60h working guy, so not much extra time to do extra documentation. If someone has this extra time, please participate. I'll support this afford.

[oojacoboo]

Hey Peter, thanks for the reply. Unfortunately I've chosen to go with another lib as I hit a brick wall on things and couldn't effectively hack my way around it. Thanks again!

[bendspoons]

Same here, i even struggled with which files i do have to include (believe it or not) :(

I think a simple code snippet in plain which can be used with C/P wwould be much appreciated (and so without your specific Page Code in your examples)

But my main question is: to obviuos color inputs are described (#defdef, rgb(),...), but how do i input xyz colors? Giving an object doesnt work...

Thanks for help!

[PitPik]

Hi @bendspoons , I just added a chapter to the README.md to describe all the files you need to set it up.

Your sentence: "But my main question is: to obviuos color inputs are described (#defdef, rgb(),...), but how do i input xyz colors?" isn't quite easy to understand... so I guess: If you use either jsColorPicker.min.js or jQueryColorPicker.min.js you just need to give the input fields a value and colorPicker will pick this up. If you don't use those implementations, just feed the color picker at initialization with some value:

var myColorPicker = new ColorPicker({
    color: 'rgba(204, 82, 37, 0.8)' // initial color (#RGB, RGB, #RRGGBB, RRGGBB, rgb(r, g, b), ...)
});

If you'r talking about setting up XYZ or Lab colors, you need to set them after initialization:

myColorPicker.setColor({X: 0.28, Y: 0.11, Z: 0.02}, 'XYZ', 0.8, true);

[bendspoons]

Yeah, thanks a lot for this, but i figured it out by myself - ok, to be honest, i had it right the whole time, but i had a simple typo error, which led to this non functioning.

Have a nice day!

[lessonpix]

Peter, I can see the honest request for "what do you need"... so I thought I'd answer it. Please don't take this as a criticism - your code works great--90% of what I need comes out of the box. And I can see that the other 10% is there.. but I can't make it work. So, here's what I need.

1. Without reading the code, I should have a list of every option for each parameter. For example, what are the "Modes"? rgb? rgba? hsv? Or do they need to be caps? etc. This would go a LONG way towards solving my problems
2. What do I need to get started? For standard JQ Plugins, there is ideally just one file, with all of the Javascript/JQuery code piled together. It's usually minimized, and sometimes there's a CSS file. With yours, I needed to download the ColorPicker files, the Color files, the CSS, and then the implementation (I think). Until I did that, nothing worked.
3. Are there any gotchas? One you addressed in the Readme - the included files had to be added in the body section... but you could have avoided this by putting them in a function() yourself. If nothing else, the example should call this out in a comment.
4. There should be an example that shows every option. It's ok if one example shows lots of options, but every option should be shown somehow. For example, I don't have an example for how to add "memoryColors". I thought adding it to the options would work, but it doesn't seem to. Is it broken? I don't know, but if I could look at a working example, I'd know what I did wrong.

I hope this helps. If you'd like help putting it together, I'd be happy to. But right now I (like others) am very frustrated and hoping I don't have to give up on this library :-/

Bill

[PitPik]

Hi Bill ( @lessonpix ) , thanks for your criticism. Its valuable (and I can handle it ;o). I know that documentation is not my strongest side as programming is more fun and I'm quite busy doing my work. I can also see that quite a lot people out there are actually using this tool already (didn't quite realize that so far) therefore, there seems to be a bit more necessity for responsibility. Ok, let's start at some point:

1. The modes are quite simple to figure out I thought: When you start the colorPicker and don't set anything, you see it in rgb-r mode meaning that on the right side (with all the buttons and input fields) you see the 'B' on 'R G B' buttons active and the color picker shows a black-to-red-to-yellow-to-green-and-back-to-black patch on the left side and a black-to-blue slider in the middle. When you play around with the color picker you can figure out what (visible) modes it can run with (by clicking the buttons) and then it's quite logic to figure out the modes you can set in the options. So, the modes that can be made visible are: rgb-r, rgb-g, rgb-b, then hsv-h, hsv-s, hsv-v and hsl-h, hsl-s and hsl-l. You can therefore see 3 different color spaces (rgb, hsv, hsl) and can start from any of their units. (confusing part here: hsb = hsv, so hsb as the buttons say is internally not available as its called hsv).
2. There is a section 'Description of Files' (https://github.com/PitPik/colorPicker#description-of-files) that explains what can / should be used: If you want to use jQuery and don't want to bother about any self-programming: jQuery_implementation/jQueryColorPicker.min.js. It contains all you need in one file (even the html, css and images). You can then start just like shown on http://www.dematte.at/cpn/jQuery_implementation/ with $('.color').colorPicker();
3. I don't quite understand what you're asking here... am I right that it's about loading the files in the body instead of in the header? If so then thanks for this one: I just fixed this and updated colorPicker. It now works both ways...
4. You're right. My examples on the demo page are too complicated to read (out of the index.js file). This color picker was meant for higher level programmers that are used to hack around and figure out by inspecting the instances... but I certainly can't assume that everybody would understand (for simpler approaches I also mad the tinyColorPicker: https://github.com/PitPik/tinyColorPicker, easier to understand and to handle and good enough for most use-cases). memoryColors are the squares on the bottom of the colorPicker. They usually fill themselves as soon as you use them and revisit the page (saved as cookies, just like the 'mode', the size of the colorPicker, etc.). If you want to disable this auto-fill mechanism and need to pre fill a set of colors there the use something like memoryColors: [{r: 100, g: 200, b: 10, a: 0.8}] in the options. This particular example here will put a greenish color on the first square. If you define more colors (up to 8) then those will also appear in the memory bar... (maybe you just had a typo or something,... I thought the description in the readme was clear enough...)

So, I hope this answered your questions so far. As soon as I find more time I will write some more understandable demos and documentation. As I mentioned before, this was initially done for higher level programmers, but I understand that this should by now be written for more common users. The whole color topic is quite complex already, so this tool should be a help and not another hurdle ;o)

Cheers and thanks for your input Peter

[lessonpix]

Thank you, Peter for the response (not sure how I missed it - sorry for the delay).

On the memoryColors, it looks like there may be a bug that uses the cookie colors regardless of what's sent in So, if I'm in a fresh browser, I get what I want, but over time, the key colors I want are replaced (likely by double clicking). I want my users to have a standard set of skin tones (they are very hard to find by hand) at the bottom... ideally, I'd like two rows (skin tones & primary/secondary colors), but that's a wish, not a bug :-) Am I missing an option to disable the cookie usage?

For some reason, when I tried to only use the JQuery file, it couldn't find the Colors class? When I added all the other files, it worked. I will try again from scratch with your newest version - thank you for making it possible to load it in the header.

As for making it more accessible ("for more common users"), many of us are actually very experienced programmers (20+ years in the profession personally). But my color picker wasn't even on the fringe of where I want to spend my time - I wanted something that "just worked" and yours was SO CLOSE! I was so happy that it looked like it did everything I needed, was in the framework I needed (JQuery) and was small and efficient. To have to dig into the code to follow how it worked derailed that joy... and I almost moved on. Having you respond is great and again, thank you.

Assuming I can get the memoryColors working, I'll see if I can get put together some supporting boilerplate to help you out with this.

Thanks again, Bill

[PitPik]

Hi @lessonpix Bill, thanks for your response. About the color memory squares: What if you leave the memory squares to the user and offer a set of clickable colors on your page (next to the input field or so, just like you can see on the demo page underneath the color wheel). This way, the user can use the colorPicker's squares as his/her tool box for experimenting and the fixed color patches that you provide as a fixed reference.

I will check again though if there is something unexpected going on with the existing memory slots... Thanks again :) Peter

[PitPik]

Hi @lessonpix again, I just experimented with the memory patches ...

var colors = jsColorPicker('input.color', {
    memoryColors: [
        {r: 100, g: 200, b: 10, a: 0.6},
        {r: 80, g: 100, b: 50, a: 0.9},
        {r: 70, g: 80, b: 10, a: 0.9},
        {r: 20, g: 200, b: 60, a: 0.9},
        {r: 88, g: 0, b: 30, a: 0.4},
        {r: 100, g: 0, b: 100, a: 0.6},
        {r: 200, g: 0, b: 0},
        {r: 200, g: 30, b: 100}
    ]
});

Not the nicest colors here ;o) but it works... If you click on the furthest right square (with the ring inside) it replaces the furthest left (and so on, that's how you save your colors there),... but if you refresh the browser, you'll get the 'pre-set' colors back. Everything as expected. Could it be that you don't want the user to manipulate the colors at all?? If that's the case then there is a way (actually 2) to prevent the user from saving colors into memory. Let me know if that's the case, then I'll show you how...

[PitPik]

@lessonpix , about your trouble initializing jqColor.js: this is only the implementation, not the whole thing. jQueryColorPicker.min.js is the whole thing including everything. Here an example:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset='utf-8'>
    <script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
    <script type="text/javascript" src="jQueryColorPicker.min.js"></script>

    <title>colorPicker jQuery implementation example</title>
</head>

<body>
<input class="color" value="#B6BD79" />
<input class="color" value="rgb(162, 63, 3)" />
<input class="color" value="hsl(32, 95%, 23%)" />
<script type="text/javascript">
var $colors = $('input.color').colorPicker({
        init: function(elm, colors) {
            elm.style.backgroundColor = elm.value;
            elm.style.color = colors.rgbaMixCustom.luminance > 0.22 ? '#222' : '#ddd';
        }
    });
</script>
</body>
</html>

$colors.colorPicker.colorPickers[0] is then your instance where you can find all the colors, options and methods...

[lessonpix]

Thanks for the feedback - I had assumed that the .min.js version was just a minified version of the JQueryColor.js file. I will try it with the min.js file.

Also, I think I would like to disable the user setting the memory colors - can you show me how?

[PitPik]

Hi @lessonpix , unfortunately there is no option to disable this but with a little hack on actionCallback it's possible in a quite fast way:

var memoryColors = [
        {r: 100, g: 200, b: 10, a: 0.6},
        {r: 80, g: 100, b: 50, a: 0.9},
        {r: 70, g: 80, b: 10, a: 0.9},
        {r: 20, g: 200, b: 60, a: 0.9},
        {r: 88, g: 0, b: 30, a: 0.4},
        {r: 100, g: 0, b: 100, a: 0.6},
        {r: 200, g: 0, b: 0},
        {r: 200, g: 30, b: 100}
    ],
    myColorPicker = jsColorPicker('input.color', {
        memoryColors: memoryColors, // initial setting
        actionCallback: function(event, type) {
            if (type === 'toMemory') { // overwriting right after repaint...
                myColorPicker.current.renderMemory(memoryColors);
            }
        }
   });

You need to update to the newest version though as there was a typo in the actionCallback: it was something like toMemery instead of toMemory

Sorry, you're using the jQuery version:

    $myColorPicker.colorPicker.colorPickers.current.renderMemory(memoryColors);