faceclick

1 <img src="raw/screenshot.png" alt="Screenshot of Faceclick popup" style="float: right; margin-left: 1em;"> 2 3 # 😀 Faceclick 4 5 A lightweight Emoji picker popup library with keyword search. 6 7 **Goals:** 8 9 * Use the "tags" from the Unicode spec for keyword searching. 10 * Show Emoji sectioned by "groups" for browsing. 11 * **Make the file size as small as possible** while doing the above. 12 * Library is one vanilla JavaScript file and one tiny CSS file. 13 14 For more about Faceclick, see the project website: 15 16 [https://ratfactor.com/faceclick/](https://ratfactor.com/faceclick/) 17 18 ## Installation 19 20 Include it on your page: 21 22 <script src="faceclick.js"></script> 23 24 ## Basic usage 25 26 This is the simplest way to use Faceclick: 27 28 FC.attach("btn1", "text1"); 29 30 The first parameter is the ID of the HTML element you want to click on to open 31 the popup. The popup will open next to the element on the screen. 32 33 The second parameter is the ID of the HTML text input element into which the 34 picked Emoji will be inserted. The insertion will happen at your text 35 entry cursor position. 36 37 See `test.html` for working examples. 38 39 ## Advanced usage 40 41 Faceclick exposes all of its methods under the `FC` namespace. They are intented 42 to be used together or composed into your own custom behavior. 43 44 The following settings can be invoked (**globally**, sorry) after FC has been loaded: 45 46 * `FC.group_clears_search` - True by default, the search box is cleared 47 when you pick a group tab. 48 * `FC.search_clears_group` - True by default, typing a search clears 49 the group tab selection. 50 * `FC.close_on_clickaway` - True by default, popups will close when the 51 user clicks anywhere outside of the popup. 52 53 This one won't work if you're using a custom callback that doesn't make use of 54 `FC.insert()`: 55 56 * `FC.close_on_pick` - True by default, popups will close when 57 you pick an Emoji and return input focus to the target text element. 58 59 Either parameter of `attach()` can be a reference to a DOM element rather than 60 an ID string: 61 62 var my_btn = document.getElementById('button9000'); 63 var my_txt = document.createElement('textarea'); 64 FC.attach(my_btn, my_txt); 65 66 To perform a custom callback when an Emoji has been picked, use the `attach_cb()` 67 helper method. Note that with this method, you _have_ to pass a DOM element: 68 69 var my_btn = document.getElementById("clicky"); 70 71 FC.attach_cb(my_btn, function(emoji){ 72 FC.close(); 73 // ... do something with emoji here ... 74 }); 75 76 The above example also demonstrates the `close()` utility method to close the 77 popup when an Emoji has been picked, which is optional. 78 79 Now is a good time to mention the `insert()` utility method. It inserts text 80 into a DOM text input element at the text cursor position. Feel free to use 81 it any way you want: 82 83 FC.insert = function(element, insert_txt); 84 85 A lower-level function for attaching a popup to a DOM element is 86 `attach_popup()`. It opens the popup next to the element and then 87 calls your callback function when an Emoji is picked: 88 89 function my_callback(){ ... } 90 91 my_button.addEventListener("click", function(){ 92 FC.attach_popup(el_click, my_callback); 93 }); 94 95 The lowest level method to open the Faceclick popup is `popup()`. 96 It takes `x` and `y` screen coordinates to display and then calls your 97 callback function with the picked Emoji: 98 99 FC.popup(x, y, my_callback); 100 101 An example of Faceclick being used with `attach_popup()` in a real project can 102 be found here: 103 104 [https://ratfactor.com/repos/famsite/html/fam.js.html#L50](https://ratfactor.com/repos/famsite/html/fam.js.html#L50) 105 106 ## Make a custom Emoji set 107 108 The `data/` directory contains a full copy of data.json from Emojibase. See 109 the README in that directory for notes about file sizes and the Ruby scripts 110 you'll find there. 111 112 But, basically, change `customizer.rb` to fit your preferences and then run the 113 `go.sh` shell script to generate a visual contact sheet HTML file (for 114 previewing your set while customizing) and a final data set for use with the 115 picker. Replace the data set in `faceclick.js` with the generated data set 116 (copy and paste!). 117 118 $ cd data 119 $ vim customizer.rb 120 $ firefox mysheet.html 121 $ ./go.sh 122 $ cat mydata.js >> ../faceclick.js 123 124 For more of the high-level ideas behind this, I recommend the project website 125 linked at the top of this document. 126 127 128 ## License and what you can do with it 129 130 I'm releasing this under the GNU GPLv3 license. Please see the 131 <a href="html/LICENSE.html">LICENSE</a> text file in this repo. 132 133 In short, you can download, modify, and distribute this program. 134 135 I'd love to hear about it if you end up using this in your project.