{"id":26506195,"url":"https://github.com/davethefrontenddev/magnetjs","last_synced_at":"2025-03-20T22:26:22.628Z","repository":{"id":143888529,"uuid":"136754954","full_name":"DaveTheFrontEndDev/MagnetJS","owner":"DaveTheFrontEndDev","description":"A javascript library for creating online / offline virtual fridge magnets.","archived":false,"fork":false,"pushed_at":"2018-12-29T00:18:15.000Z","size":6405,"stargazers_count":17,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-20T07:17:08.931Z","etag":null,"topics":["es6-javascript","fun","gulp","javascript-modules","socket-io"],"latest_commit_sha":null,"homepage":"http://www.online-fridge.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DaveTheFrontEndDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-09T20:17:01.000Z","updated_at":"2023-09-15T14:49:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"c1e6b764-aa53-4225-8c75-93f15a8f0abb","html_url":"https://github.com/DaveTheFrontEndDev/MagnetJS","commit_stats":null,"previous_names":["mrvann/magnetjs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveTheFrontEndDev%2FMagnetJS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveTheFrontEndDev%2FMagnetJS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveTheFrontEndDev%2FMagnetJS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveTheFrontEndDev%2FMagnetJS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DaveTheFrontEndDev","download_url":"https://codeload.github.com/DaveTheFrontEndDev/MagnetJS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244702394,"owners_count":20495900,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["es6-javascript","fun","gulp","javascript-modules","socket-io"],"created_at":"2025-03-20T22:26:21.931Z","updated_at":"2025-03-20T22:26:22.620Z","avatar_url":"https://github.com/DaveTheFrontEndDev.png","language":"JavaScript","readme":" ![Magnet JS](docs/resources/magnetjs-title.gif)\n\n# MagnetJS\n\n\u003e An open source javascript library that allows you to create interactive fridge magnets.\n\n[![npm version](http://img.shields.io/npm/v/magnetjs.svg?style=flat)](https://npmjs.org/package/magnetjs \"View this project on npm\")\n[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)\n[![npm downloads](https://img.shields.io/npm/dt/magnetjs.svg)](https://npmjs.org/package/magnetjs \"View this project on npm\")\n\n__Live Example:__ [www.fridgeee.com/example](http://www.fridgeee.com/example)\n\n__Live Example (with dark theme):__ [www.fridgeee.com/codetheme](http://www.fridgeee.com/codetheme)\n\n## Overview\n\nMagnetJS is an open source javascript library for creating and interacting with virtual fridge magnets.\n\nThe library can be used in local mode _(local movement of magnets)_, or using the [fridgeee.com](http://www.fridgeee.com) api (anybody can move the magnets in real-time).\n\nIt is designed to be modular and include other components in the future (for example post-it notes).\n\nSee the [Quick Start](#quick-start) section to get started.\n\n## Quick Start\n\nTo get started using MagnetJS, include the library.\n\n```html\n\u003cscript src=\"magnet.min.js\"\u003e\u003c/script\u003e\n```\n\nAdd a target to your website (this is where you board will be built).\n\n```html\n\u003cdiv id=\"root\" /\u003e\n```\n\nCreate your board (`target:` is the 'id' of your target element)\n\n```javascript\nconst board = new Magnet({ target: 'root' });\n```\n\nAfter the dom has loaded, mount the board.\n\n```javascript\nwindow.onload = () =\u003e {\n  board.mount();\n};\n```\n\nAnd Vualá!!\n\n![MagnetJS Example](docs/resources/magnetjs-example.gif)\n\n## Making changes\n\nTo make changes to the library and test it out.\n\n```console\nnpm install\n```\n\nAnd run the example app:\n\n```console\nnpm start\n```\n\nThe files that load the board are in `example/html/.`.\n\n## Methods\n\n### mount()\n\nMounts the board to the target (set in config). This must only be called once the DOM has loaded.\n\n## Config\n\nAll values apart from the target are optional, however if you include a theme or item config they must be complete.\n\n### id\n\nThe `id:` value is __not__ the target element for your board. This is used to identify the board when using online mode (see [Online Mode](#Online-Mode)). The board can also be viewed by visiting www.fridgeee.com/{id here}.\n\n### target\n\nThe `target:` value mounts the board to the DOM element with that id. In the example this is `\"root\"`.\n\n### width\n\nIn pixels, the width of the board (not target element).\n\n### height\n\nIn pixels, the height of the board (not target element).\n\n### items\n\nThis contains the config for items on the board, they can come in one of two formats.\n\n#### items -\u003e Array\n\nArray of items (for example, a letter item config as described [here](src/component/Letter.README.md))\n\n#### items -\u003e Object\n\nItems config, this is the information that is required to generate items.\n\n##### spawn\n\nThe number of components to generate for the board.\n\n##### options\n\nAn object containing options for the items. These are defined in the component config (for example [here](src/component/Letter.README.md)).\n\n### theme\n\nAn array of styles to be used as a theme for the board and its content.\n\nIf the structure of this config seems a little odd it is because it must also mimic the database structure for the use of the [online-fridge.com](http://www.online-fridge.com) api.\n\nEach style is a javascript object with the following structure:\n\n#### code\n\nThis value should be one of the following:\n\n* `background` - This means to set the style to the background of the board, this can be an rgb value for example.\n\n* `color` - This is to create a specific theme color that can be uniquely defined per item (see item 'color' values in the Letter component [README](src/component/Letter.README.md))\n\n* Component name, e.g `letter` - This means a style to set for a specific item\n\n#### id\n\nThis value should always be 1 unless it the style object has `code: 'color'`. If it has a 'color' code then it should increment per value and be used as a unique identifier for each color.\n\n#### key\n\nThis value must be one of the following:\n\n* The key in css ['key / value pairs'](https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax) but with camelCase instead of css hyphen-case.\n\n* `rgb`, which would convert into an rgb color value. This is then handled differently depending on the `code` value of the style object. For example, the `background` code will set this value as the background.\n\n#### value\n\nThis will the one of the following:\n\n* The value in css ['key / value pairs'](https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax). This value can also perform calculations on the color value of its item. To do this you should use the following syntax:\n\n```\n    key: \"textShadow\",\n    value : \"0 10px 0 rgb({[r]-50},{[g]-50},{[b]-50})\"\n```\n\nThis is the same as an [es6 template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) but without the `$` and assuming that the rbg values are storage as variable with the name `r`, `g` and `b`. This allows you also use variations of the rgb color values.\n\n### Example config\n\n```javascript\nvar config = {\n  id: 'test', // ID of the board (if using sockets)\n  target: 'root', // ID of the element to build the board onto\n  width: 1000, // Width of the board (px)\n  height: 1000, // Height of the board (px)\n  items: {\n    spawn: 100, // Spawn 100 items to the board\n    options: {\n      text: ['Toast','is','Food','for','my','belly'], // Text combinations to create the items with.\n      color: [1,2,3,4,5], // The themes color unique identifiers.\n      type: 'Letter' // The item type\n    }\n  },\n  theme: [\n    {code: \"background\", id: 1, key: \"rgb\", value: \"50,50,50\"}, // Set the board background to rgb(50,50,50)\n    {code: \"color\", id: 1, key: \"rgb\", value: \"132,159,187\"}, // First theme color\n    {code: \"color\", id: 2, key: \"rgb\", value: \"179,159,161\"}, // Second theme color\n    {code: \"color\", id: 3, key: \"rgb\", value: \"110,201,151\"}, // Third theme color\n    {code: \"color\", id: 4, key: \"rgb\", value: \"183,101,191\"}, // Fourth theme color\n    {code: \"color\", id: 5, key: \"rgb\", value: \"255,132,107\"}, // Fifth theme color\n    {code: \"letter\", id: 1, key: \"fontFamily\", value: \"'Baloo Bhaina', cursive\"}, // Font family for `letter` component\n    // Text shadow for the `letter` component that uses the theme color to build a shade.\n    {\n      code: \"letter\",\n      id: 1,\n      key: \"textShadow\",\n      value : \"0 1px 0 rgb({[r]-50},{[g]-50},{[b]-50}), 0 2px 0 rgb({[r]-50},{[g]-50},{[b]-50}), 0 3px 0 rgb({[r]-50},{[g]-50},{[b]-50}), 0 4px 0 rgb({[r]-50},{[g]-50},{[b]-50}), 0 5px 0 rgb({[r]-50},{[g]-50},{[b]-50}), 6px 6px 20px rgba(0,0,0,.1)\"\n    }\n  ]\n};\n```\n\n## Online Mode\n\nTo enable the use of the [fridgeee.com api](http://www.fridgeee.com) you must:\n\nLoad socket.io from online-fridge.com\n\n```html\n\u003cscript src=\"http://www.fridgeee.com/socket.io/socket.io.js\"\u003e\u003c/script\u003e\n```\n\nInclude the id of the board you want to access in the config.\n\n```javascript\nconst board = new Magnet({\n target: 'root',\n id: 'example'\n});\n```\n\n## Compatibility\n\nBrowser support could stretch back further but will need further testing to confirm.\n\n| Device  | Browser | Version     |\n|---------|---------|-------------|\n| Mobile  | Safari  | IOS 11.4.0+ |\n| Mobile  | Chrome  | 67.0.x+     |\n| Desktop | Chrome  | 67.0.x+     |\n| Desktop | Safari  | 11.1+       |\n| Desktop | Firefox | 40.0.2+     |\n\n## FAQ\n\n### Why did you make this?\n\nFor fun.... mostly. This was also my project for familiarising myself with sockets and javascript modules.\n\n### Why did you not choose canvas?\n\nThe decision for not using canvas was based on the idea that anybody can add to their own components. As DOM is more common  I decided to not use canvas.\n\n## What I would like to change\n\n- There is some ambiguity between how classes are accessed, I would like to re-evaluate the class structure with [SOLID](https://deviq.com/solid/) design.\n\n- I would like to look at better alternative ways to load css, the current method of dynamically adding stylesheets to the webpage is probably not the bet option.\n\n- Move the config initialisation out of the socket class, this is more of a TODO as a result from originally not designing it to work offline.\n\n- Make this compatible for modern javascript libraries like ReactJS and VueJS. I started this project early on in my career as a developer and was not fully aware of these technologies and their importance at the time.\n\n## Release History\n\n* 0.1.0\n    * The first proper release. Includes all core functionality for magnets and socket.io implementation.\n    \n## Meta\n\n__MrVann__ - [https://github.com/MrVann](https://github.com/MrVann)\n\nDistributed under the MIT license. See [``LICENSE``](LICENSE) for more information.\n\n## Contributing\n\n1. Fork it (\u003chttps://github.com/MrVann/MagnetJS/fork\u003e)\n2. Create your feature branch (`git checkout -b feature/fooBar`)\n3. Commit your changes (`git commit -am 'Add some fooBar'`)\n4. Push to the branch (`git push origin feature/fooBar`)\n5. Create a new Pull Request\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavethefrontenddev%2Fmagnetjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavethefrontenddev%2Fmagnetjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavethefrontenddev%2Fmagnetjs/lists"}