Post by Carlos (Panels App Developer) on Mar 2, 2018 22:29:25 GMT
Developer Guide
Creating a custom Panel in the Panels App can be done in two ways. The "easy" way involves using the built in Panel Creator. This allows you to add buttons, images, etc. But, for a lot of use cases, this isn't enough. If we want to truly have control of the way our panels work, we'll need to hand-craft the panels with some code.
So what is a Panel?
If you have a panel created, or installed, you can export that panel via Manage Panels -> Select Panel -> Export. All files in the system are saved as .panelpkg files. What's a .panelpkg file? It's nothing but a zip file. If you change the extention to ".zip", and open the file up, you'll see something that will be very familiar to web developers. There's an index.html file, some javascript files, and some css files. At its core, a panel is really just a website! The Panel Creator is generating a website for you. If you know html/js/css, there's absolutely nothing stopping you from making your own panel, zipping it up, changing the .zip file extension to .panelpkg, and importing it!
Granted, there are a couple of things that need to be included that wouldn't be found in your standard website, and we'll go over them in detail in this guide, but it's important to understand that, at its core, this is how the application works. Anything you can do with JS/Html, you can do as part of a panel.
Hello World
<body>
<a>
<button style="background-color: green; height: 100px; width: 200px">Button</button>
</a>
</body>
If you open this up in your browser, you'll just see a green button. Not the most exciting, but we gotta start somewhere.
We'll also need to add a "Settings.json" file right next to the index.html file. Make the Settings.json file look like this
{
"KeyBindings":{ },
"LabelBindings":{ },
"Program":"C:\\Windows\\explorer.exe"
}
We'll go over what these mean in a bit (though you may already have an idea).
Now this is a minimal panel! Zip up the contents of this folder (make sure that the index.html file and Settings.json file are at the root of the zip file), and change the extension to .panelpkg. Now this panel is ready to be imported. From the manage tab, you can click "Import Panel", select your newly created .panelpkg file, and it will be imported into the system. If you connect the Panels App on your tablet to your computer, you should see your Panel show up on your tablet when you open a Windows explorer window on your desktop!
Let's make it do stuff.
So, at this point, we have a working Panel but it's not really doing much. We can see and click on a button on the tablet, but there's no way to configure the button text or key bindings in the Manage Panels section of the desktop program. That's what Settings.json is for. First, let's make a couple of quick modifications to the index.html file<body>
<a href="panelsapp://Button">
<button style="background-color: green; height: 100px; width: 200px">$$Button$$</button>
</a>
</body>
So, there are two changes here. First, we changed the button text to be $$Button$$. This will actually tell Panels to find a LabelBinding in Settings.json with the name Button, and replace $$Button$$ with that value. This will let users change that label binding in the Manage Panels section of the application.
Secondly, and perhaps more confusingly, is the href we added. Your panel is capable of making any web requests you'd like; the app isn't going to block any outgoing http:// or https:// requests. However, it is constantly searching for any "panelsapp://" requests being sent by your little website. If the app sees an outgoing "panelsapp://" request, it will intercept that request, and forward it to the Panels Desktop application instead. What happens upon that request depends on your Settings.json file. Let's update that one now.
{
"KeyBindings":{
"Button":{
"Type": 0,
"Value": ""
}
},
"LabelBindings":{
"Button": "My Button Text"
},
"Program":"C:\\Windows\\explorer.exe"
}
We added a KeyBinding object and a LabelBinding object, both named "Button". Remember, we're naming it "Button" because that's what corresponds to what we added in our html file. The KeyBinding "Type" property is set to 0, which means it'll interpret the value as Key Presses. I left the value blank, as both the "Type" and "Value" properties can be modified within the Panels Desktop Application. Let's go ahead and zip up those files again and create the .panelpkg file (by renaming the zip file). Once that's done, head over to your Panels Desktop application, go to "Manage Panels" and select the panel you created in the previous step. Once you've selected the panel, click "Update", and select the new package. When prompted, say you don't want to keep existing key bindings".
If everything has gone well, you should now see an actual, configurable button row in the Panels Desktop app. Also, if you navigate again to a Windows Explorer window, you should see that your green button now says "My Button Text". This can be changed via the application without having to mess with the Settings.json file manually anymore. You can also set your key bindings for that button, so that whenever you press it, those keys are pushed!
That's all it takes to make a panel! You may have noticed that you're able to pinch, zoom, and scroll on the tablet which isn't really ideal for a panel (usually). I recommend setting some meta tags to handle the pinching and zooming problem, and some styles on your html and body elements to handle the scrolling. Here's what the final html file would look like with those changes
<head>
<meta name="viewport" content="width=device-width, user-scalable=no, viewport-fit=cover" />
<style>
html, body {
position: fixed;
height: 100vh;
width: 100vw;
overflow-y: hidden;
overflow-x: hidden;
-webkit-overflow-scrolling: touch;
}
</style>
</head>
<body>
<a href="panelsapp://Button">
<button style="background-color: green; height: 100px; width: 200px">$$Button$$</button>
</a>
</body>
Now we have a nice, static panel that can't be pinched, zoomed, or scrolled. I hope you find this a helpful kicking off point for making your own panel by hand. I'll be writing some more documentation shortly about some more advanced topics like DataFeeds, which allow the desktop application to send data back to the table for more immersion.
Thanks, and happy coding!