[{"data":1,"prerenderedAt":439},["ShallowReactive",2],{"doc-content/docs/developer/guide":3,"doc-surroundings/docs/developer/guide":348,"docs-navigation":357},{"path":4,"draft":5,"date":6,"dateUpdated":7,"title":8,"body":9,"description":347,"image":6,"imageAlt":6},"/docs/developer/guide",false,null,"2025-05-15","Widget Developer Guide",{"type":10,"value":11,"toc":337},"minimark",[12,16,28,31,34,37,40,43,48,64,71,82,84,88,91,98,106,112,115,118,181,188,194,197,267,273,284,286,290,293,300,307,318,321,324,333],[13,14,8],"h1",{"id":15},"widget-developer-guide",[17,18,19,20,27],"p",{},"Hologram is a Mac OS application that lets you display widgets on your desktop. Hologram widgets are written in HTML, CSS, and Javascript using the ",[21,22,26],"a",{"href":23,"rel":24},"https://vuejs.org",[25],"nofollow","Vue.js"," Javascript framework.",[17,29,30],{},"Because widgets are built with web technologies, anyone with basic web development skills should have the ability to craft their own widgets. And for those that are expert web developers, the sky is the limit in terms of what types of widgets can be conceived and built.",[17,32,33],{},"Why Vue? Because Vue provides (among other things) the advanced DOM manipulation capability necessary to manage a collision-free multi-widget environment. Hologram is a Webkit layer that resides above the Mac desktop, but below the files and folders on the desktop. Vue allows each Widget to operate discreetly, without interfering with other Widgets.",[17,35,36],{},"The Hologram application comes with built-in developer tools, including APIs, a suite of functions, and a hot-reloading server so you can see your code changes live while you work. In fact, one click will scaffold a new widget and launch the dev server so you can start coding immediately. We wanted to make the process of creating a widget as fast and easy as possible.",[17,38,39],{},"This guide will walk you through the basics of widget development.",[41,42],"hr",{},[44,45,47],"h2",{"id":46},"creating-a-widget","Creating a Widget",[17,49,50,51,55,56,59,60,63],{},"From within the Hologram application, open the ",[52,53,54],"code",{},"preferences"," window, go to the ",[52,57,58],{},"widgets"," page and click the ",[52,61,62],{},"show widget developer tools"," button. Doing so will reveal the developer icon in the left column navigation of Hologram's main window.",[17,65,66,67,70],{},"Then navigate to the developer page and click the ",[52,68,69],{},"New Widget"," button. Hologram will ask you to name your widget, then it will let you select from one of several starter widget templates (Hello World, Simple Dash, Simple Weather). When you click the submit button, Hologram will create all the base assets (described below) so you can get started building your widget.",[72,73,74],"alert",{},[17,75,76,77,81],{},"To access the files Hologram just created, click on your new widget from the developer page, then click the ",[78,79,80],"strong",{},"show in finder"," button. You can now open the files in a text editor.",[41,83],{},[44,85,87],{"id":86},"anatomy-of-a-widget","Anatomy of a Widget",[17,89,90],{},"A widget will minimally consists of the following four assets:",[92,93,95],"h3",{"id":94},"widgetjson",[52,96,97],{},"widget.json",[17,99,100,101,105],{},"This file contains information about your widget such as its name, version, etc. It's also where all the user-editable settings associated with a widget will be defined. This file is explained in detail in the ",[21,102,104],{"href":103},"/docs/developer/widget-config","Widget Config"," page.",[92,107,109],{"id":108},"indexjs",[52,110,111],{},"index.js",[17,113,114],{},"The Javascript entry point to your widget. This is where most of your code will live. It must export a valid Vue JS component using ES6 module syntax. Widgets must also extend the Hologram widget component.",[17,116,117],{},"Here is a minimalist example of a \"Hello World\" Widget.",[119,120,125],"pre",{"className":121,"code":122,"language":123,"meta":124,"style":124},"language-js shiki shiki-themes github-dark github-dark","export default {\n    extends: HologramWidget,\n    template: /* html */ `\n    \u003Cdiv>Hello World!\u003C/div>\n    `\n}\n","js","",[52,126,127,143,149,163,169,175],{"__ignoreMap":124},[128,129,132,136,139],"span",{"class":130,"line":131},"line",1,[128,133,135],{"class":134},"sOPea","export",[128,137,138],{"class":134}," default",[128,140,142],{"class":141},"suv1-"," {\n",[128,144,146],{"class":130,"line":145},2,[128,147,148],{"class":141},"    extends: HologramWidget,\n",[128,150,152,155,159],{"class":130,"line":151},3,[128,153,154],{"class":141},"    template: ",[128,156,158],{"class":157},"sJ8bj","/* html */",[128,160,162],{"class":161},"s4wv1"," `\n",[128,164,166],{"class":130,"line":165},4,[128,167,168],{"class":161},"    \u003Cdiv>Hello World!\u003C/div>\n",[128,170,172],{"class":130,"line":171},5,[128,173,174],{"class":161},"    `\n",[128,176,178],{"class":130,"line":177},6,[128,179,180],{"class":141},"}\n",[17,182,183,184,105],{},"A more thorough explanation can be found in the ",[21,185,187],{"href":186},"/docs/developer/widget-class","Widget Class",[92,189,191],{"id":190},"stylescss",[52,192,193],{},"styles.css",[17,195,196],{},"This file contains your widget's CSS. The styles are automatically scoped and injected into the widget to prevent conflicts with other widgets.",[119,198,202],{"className":199,"code":200,"language":201,"meta":124,"style":124},"language-scss shiki shiki-themes github-dark github-dark","// This\n.widget-wrapper {\n    color: green;\n}\n// Will automatically become:\n.widget-css__my-widget-name .widget-wrapper {\n    color: green;\n}\n","scss",[52,203,204,209,217,232,236,241,251,262],{"__ignoreMap":124},[128,205,206],{"class":130,"line":131},[128,207,208],{"class":157},"// This\n",[128,210,211,215],{"class":130,"line":145},[128,212,214],{"class":213},"sFR8T",".widget-wrapper",[128,216,142],{"class":141},[128,218,219,223,226,229],{"class":130,"line":151},[128,220,222],{"class":221},"s8ozJ","    color",[128,224,225],{"class":141},": ",[128,227,228],{"class":221},"green",[128,230,231],{"class":141},";\n",[128,233,234],{"class":130,"line":165},[128,235,180],{"class":141},[128,237,238],{"class":130,"line":171},[128,239,240],{"class":157},"// Will automatically become:\n",[128,242,243,246,249],{"class":130,"line":177},[128,244,245],{"class":213},".widget-css__my-widget-name",[128,247,248],{"class":213}," .widget-wrapper",[128,250,142],{"class":141},[128,252,254,256,258,260],{"class":130,"line":253},7,[128,255,222],{"class":221},[128,257,225],{"class":141},[128,259,228],{"class":221},[128,261,231],{"class":141},[128,263,265],{"class":130,"line":264},8,[128,266,180],{"class":141},[92,268,270],{"id":269},"cardpng",[52,271,272],{},"card.png",[17,274,275,276,279,280,283],{},"The widget card image. Dimensions should be ",[52,277,278],{},"800px"," by ",[52,281,282],{},"550px",". Please look at the default widget cards for examples of what a typical card looks like.",[41,285],{},[44,287,289],{"id":288},"development-server","Development Server",[17,291,292],{},"It's hard to debug code when working with Hologram's live Webkit layer because the web inspector and Javascript console are not accessible, so Hologram includes a dev server to assist you during development. The server auto-detects file changes and refreshes your web browser for convenience.",[17,294,295,296,299],{},"The dev server can be launched from within the Hologram developer page by clicking the ",[52,297,298],{},"Start Dev Server"," button.",[17,301,302,303,306],{},"This will create a server on port ",[52,304,305],{},"9080",".",[17,308,309,310,313,314,317],{},"If Safari is your default browser you can click the ",[52,311,312],{},"open browser"," button. Otherwise, you can launch Safari manually and go to ",[52,315,316],{},"localhost:9080",". Hologram uses Webkit, so it's highly recommended that you develop using Safari.",[17,319,320],{},"The server home page will show a list of all your Hologram themes. Select one, then add your new widget to your theme.",[17,322,323],{},"You are now ready to begin writing code!",[72,325,327],{"title":326},"Note",[328,329,330],"template",{"v-slot:description":124},[17,331,332],{},"Hologram does not include a bundler/compiler such as Webpack, or tools such as TypeScript or Sass. There is no prohibition against them, so if you have a particular workflow you prefer to use, you are certainly welcome to adopt it.",[334,335,336],"style",{},"html pre.shiki code .sOPea, html code.shiki .sOPea{--shiki-default:#F97583;--shiki-dark:#F97583}html pre.shiki code .suv1-, html code.shiki .suv1-{--shiki-default:#E1E4E8;--shiki-dark:#E1E4E8}html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}html pre.shiki code .s4wv1, html code.shiki .s4wv1{--shiki-default:#9ECBFF;--shiki-dark:#9ECBFF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sFR8T, html code.shiki .sFR8T{--shiki-default:#B392F0;--shiki-dark:#B392F0}html pre.shiki code .s8ozJ, html code.shiki .s8ozJ{--shiki-default:#79B8FF;--shiki-dark:#79B8FF}",{"title":124,"searchDepth":145,"depth":145,"links":338},[339,340,346],{"id":46,"depth":145,"text":47},{"id":86,"depth":145,"text":87,"children":341},[342,343,344,345],{"id":94,"depth":151,"text":97},{"id":108,"depth":151,"text":111},{"id":190,"depth":151,"text":193},{"id":269,"depth":151,"text":272},{"id":288,"depth":145,"text":289},"Introduction to developing widgets for Hologram.",[349,353],{"title":350,"path":351,"stem":352,"children":-1},"Settings","/docs/settings","docs/4.settings",{"title":354,"path":186,"stem":355,"sectionTitle":356,"children":-1},"Hologram Widget Class","docs/developer/02.widget-class","Building Widgets",[358],{"title":359,"path":360,"stem":361,"children":362,"navigation":364},"Welcome to Hologram","/docs","docs/0.index",[363,365,369,373,374,433],{"title":359,"path":360,"stem":361,"navigation":364},true,{"title":366,"path":367,"stem":368,"navigation":364},"Themes & Wallpapers","/docs/themes","docs/1.themes",{"title":370,"path":371,"stem":372,"navigation":364},"Widgets","/docs/widgets","docs/2.widgets",{"title":350,"path":351,"stem":352,"navigation":364},{"title":375,"navigation":376,"sectionTitle":377,"collapsible":364,"path":378,"stem":379,"children":380,"page":5},"Developer",{"sectionTitle":377,"collapsible":364},"Developing Widgets","/docs/developer","docs/developer",[381,383,385,387,391,395,399,403,407,411,417,421,425,429],{"title":8,"path":4,"stem":382,"navigation":364},"docs/developer/01.guide",{"title":354,"path":186,"stem":355,"navigation":384,"sectionTitle":356},{"sectionTitle":356},{"title":104,"path":103,"stem":386,"navigation":364},"docs/developer/03.widget-config",{"title":388,"path":389,"stem":390,"navigation":364},"Widget Settings","/docs/developer/widget-settings","docs/developer/04.widget-settings",{"title":392,"path":393,"stem":394,"navigation":364},"Widget Color Settings","/docs/developer/widget-color-settings","docs/developer/05.widget-color-settings",{"title":396,"path":397,"stem":398,"navigation":364},"Creating Widget Presets","/docs/developer/widget-presets","docs/developer/06.widget-presets",{"title":400,"path":401,"stem":402,"navigation":364},"Making Widgets Scale","/docs/developer/making-widgets-scale","docs/developer/07.making-widgets-scale",{"title":404,"path":405,"stem":406,"navigation":364},"Simple Widget Example","/docs/developer/simple-example","docs/developer/07.simple-example",{"title":408,"path":409,"stem":410,"navigation":364},"Apple Script","/docs/developer/apple-script","docs/developer/08.apple-script",{"title":412,"path":413,"stem":414,"navigation":415,"sectionTitle":416},"Hologram API","/docs/developer/api","docs/developer/10.api",{"sectionTitle":416},"API Reference",{"title":418,"path":419,"stem":420,"navigation":364},"Weather","/docs/developer/weather","docs/developer/11.weather",{"title":422,"path":423,"stem":424,"navigation":364},"Timer","/docs/developer/timer","docs/developer/12.timer",{"title":426,"path":427,"stem":428,"navigation":364},"Utility Class","/docs/developer/util","docs/developer/13.util",{"title":430,"path":431,"stem":432,"navigation":364},"Third Party Libraries","/docs/developer/third-party","docs/developer/14.third-party",{"title":434,"path":435,"stem":436,"navigation":437,"sectionTitle":438},"Frequently Asked Questions","/docs/faq","docs/faq",{"sectionTitle":438},"Help",1755585912837]