Previous: Making Persisted Server Changes
What makes a good user interface? Hmmm… beats me! And usually it does. I probably spend ten times more brain power on UI than the server side and it always feels like I’m fumbling around in the dark. I always concede the way something should look to others. In fact, I actively go hunting for people willing to take this abuse from me. I retired from a large corporate software house. I worked server side and we had people designing and building the Markup and CSS. Unfortunately, they were never able to wire up to our API’s. It was definitely an us and them situation. I felt back then there was a better way.
InqPortal is a five year culmination of trying my best to simplify, simplify… simplify… the client side development by shoveling as much of the complexity into little black boxes that I can just wrap up and know they’ll just work! The fact that it fits in a pinky-size ESP8266 is just gravy.
Whether people are in the Microsoft MVC ASP.NET, IIS world or the JavaScript/Java/PHP/Apache world, web-development systems attempt making development simple. They all achieve “easy” with different levels of success. Some handle everyday tasks with ease, yet become mind-boggling painful when you reach for something not in their black-box. I worked on a product that one installation could easily run into a million dollars. Yet for all our diligence and expertise, once a page was loaded there was no dynamic update. Person 1 could open a form and person 2 in another department or another country could open the same form, make a change. Person 1, not knowing any better could easily trump the person 2’s data and neither would know it happened.
I believe with version 5, InqPortal has reached a new level of ease. The most common tasks are simply… no longer tasks at all. And things that we used to consider unachievable are now trivial. And when you need to add some new exotic task, InqPortal will be there to help, not get in the way. Take the corporate concurrency issue we wouldn’t even tackle, InqPortal does it automatically and all the time without ANY work on your part. Enough horn-blowing and sunshine… let’s jump in!
Jump Start
We will continue with out FirstPortal project. Although simplistic, it has all the components. It reads a “sensor” creates data and needs to display results. It has variables that need adjusting from the outside world. It needs management tools. All these are provided by the InqPortal Admin during development. Now all we need is a friendly user interface for our end-users. The InqPortal Admin, knows the form of your data already, so why can’t it help get us started. Now in version 5, it can. We’ve added a page generator.
The page generator takes your published variables and generates a rather bland form. But with all its blandness, it still has dynamic updating of variables, permits data entry and submission to your server. We really have only three choices. You can change the title which is the name that goes in the browser’s tab. You can make a styling choice. The Tabular version will look identical to your App tab in the Admin. The Individual Elements version is more like a data entry form.
We also include the option to add a Histogram to the form. This feature has been in the Admin for several years now and I’ve forgotten how to re-use it on too many occasions. I like using them in my projects and this way I don’t have to go dumpster diving through old code to re-implement one. I just let the generator do it. If you don’t need it, you can just leave the entry blank and it won’t go into the form. The entry line uses the exact same form as the History tab configuration. In fact if you have configured the History tab, this field will be prepopulated with your configuration. Another good thing about having this rather complex GUI item in the form, is it shows you how to intercept data coming from the server and apply it to any other custom widget you decide to use. Let’s see what it gives us… Press the Download button and save your custom html page to you computer.
Inspecting the Generation
If you are familiar with HTML, this will look down-right normal. There are only three places in here that have anything to do with InqPortal! The first is including the InqPortal.js file that handles all the “wiring-up” and communication duties. If this line is not present, it won’t talk and listen to your ESP8266 server. There are two set(); methods called. Once when the Enter key is pressed and the second when an Update button is clicked. There is nothing else required.
This page is yours to do as you please. If your page is meant to be a read-only page, you could get rid of the set() methods. All the HTML class names are purely tied to cosmetic aspects that are either present near the top of the file or are in the InqPortal’s default InqStyle.css. You are free to add you own style sheets and change any or all class names. Again, there are no magic class bindings going on behind the scenes. Delete, add, change anything you like. The portion surrounded by the yellow box is the portion that was generated based solely on your published headings and variables. Read-only variables are in <span> elements, Read-Write variables are in <input> elements. The input types are defined depending on whether they were character buffers or numbers on your server. The only “magic” that bind these to your server is the id. You’ll note that these element id’s are the aliases as defined in your Sketch. In this example, we only have four. You may have many, many more and some pages you create may only need a small subset. Simply delete the elements you don’t need for the page you want to make. Just because they were generated here doesn’t mean they have to stay in this page. In other words everything here is fair game.
Trying it out
Make your code changes to the file. If you add other links to your own style sheets, JavaScript and/or image files, gather them all and upload everything to your InqPortal Admin Files tab. Like any other webserver, pages hosted on InqPortal can gather assets from other servers on the Internet. In fact early versions of InqPortal used to create the Histograms based on Google Charts. Unfortunately, they do not permit you to download the JavaScript library and we needed a solution that might not have access to the Internet. Using chart.js solved that problem.
In our example, we won’t be making any changes, and we took the default file name InqPortalStarter.html so we can simply upload the one file generated.
Note: Back in the Adding Web Content, we learned how to load up your ESP8266 “server” with content.
Once it’s on the server, you can now browse to it. Depending whether you are on the built-in connection or your LAN connection, simply browse to the page… either 10.10.10.10/InqPortalStarter.html or http://FirstPortal/InqPortalStarter.html respectively and you should get…
You will see that it updates based on you using the onInterval() method in the Sketch. It also allows you to make changes to the read/write published variables and Update the server. The calculations will take place on the next interval reflecting your constants being changed. The quickest built client around… three clicks.
This is the completion of the basic tutorial. We have walked you through the complete process from building your Arduino development environment to building your server side application while using the Admin to monitor and debug the app. And finally, here, we’ve finished up with a custom starter page ready for your artistic interpretation. There are many more, advanced topics under InqPortal Topics.