-
Notifications
You must be signed in to change notification settings - Fork 2
/
floreantpos.html
168 lines (139 loc) · 17.4 KB
/
floreantpos.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
<html>
<head>
</head>
<body style = "margin-left: 10%; margin-top: 48px;max-width:640px; background-color: #E1F5FE">
<h1><span style="font-family:arial,helvetica,sans-serif;">How to access FloreantPOS w/ a PC, Phone, or Tablet</span></h1>
<span style="font-family:arial,helvetica,sans-serif;">By fattire (Twitter:<a href="https://twitter.com/fat__tire">@fat__tire</a>)
<p><span style="font-family:arial,helvetica,sans-serif;">The goal: Access <a href="http://floreantpos.org">FloreantPOS</a> (aka "Floreant", a neat-o point-of-sale open source package) on a tablet, phone, or PC.... without having to install any complex or proprietary software. And using only open-source.</span></p>
<p><span style="font-family:arial,helvetica,sans-serif;">Here's a link to my demo: <a href="https://drive.google.com/file/d/0B_oPSXZoVv8HeTNzVmd0RGtldHM/view">video</a></span></p>
<p><span style="font-family:arial,helvetica,sans-serif;">For this tutorial I'm going to assume you're using Ubuntu Linux. In fact, I <a href="https://github.com/fat-tire/floreantpos_updater">wrote a script</a> that will automatically install Floreant for you on Ubuntu... and keep it current as the code is updated.</span></p> I've also mirrored <a href="https://sourceforge.net/p/floreantpos/code/HEAD/tree/">source code from Sourceforge.net's subversion repository</a> on github <a href="https://github.com/fat-tire/floreantpos">here</a>, although by the time you read this it is likely not up to date, but still might be useful for quick searches or whatever.
<p><span style="font-family:arial,helvetica,sans-serif;">My script (assuming it still works) puts the latest build of Floreant on your Desktop in a folder called <span style="font-family:courier new,courier,monospace;">active_floreantpos</span>, so that's the name I'm going to use in this example.</span></p>
<p> </p>
<p><strong><h3><font face="arial, helvetica, sans-serif">STEP ONE: INSTALL FLOREANTPOS WITH MY SCRIPT ABOVE</font></h3></strong></p>
<p><u><font face="arial, helvetica, sans-serif">Note: You must use a 64-bit version of Ubuntu.</font></u></p>
<p><font face="arial, helvetica, sans-serif">So I'm going to assume you've run the script and you've got Floreant ready to go. Now, how to transform it into something that can be accessed by any PC, Mac, tablet, or phone?</font></p>
<p> </p>
<p><span style="font-family:arial,helvetica,sans-serif;"><strong><h3>STEP TWO: SET UP FLOREANTPOS AS A WEB APP</h3></strong></span></p>
<p><img src="https://i.imgur.com/b0DxlER.png" style="width: 50%;" /></p>
<p><span style="font-family:arial,helvetica,sans-serif;"><strong>The secret sauce is <a href="http://webswing.org/">Webswing</a></strong>. It's an open source, HTML5-only (no non-web technologies) web server that serves Java swing apps directly to the web.</span></p>
<p><span style="font-family:arial,helvetica,sans-serif;">Since FloreantPOS is a Java app that uses Swing for its UI, there's not much to it than that!</span></p>
<p><span style="font-family:arial,helvetica,sans-serif;">The goal: <u>Make FlorantPOS a "web app" that can be accessed via HTTP on any device!</u> That is, ANY phone, tablet, PC, or whatever-- with a modern web-browser should be able to use this web app.</span></p>
<p><span style="font-family:arial,helvetica,sans-serif;">All they need is the URL and a username/password. These web apps versions</span><span style="font-family: arial, helvetica, sans-serif;"> are</span><span style="font-family: arial, helvetica, sans-serif;"> able to run together simultaneously</span><span style="font-family:arial,helvetica,sans-serif;"> with traditional FloreantPOS devices. For lightweight/inexpensive touch devices, it just a lot easier to point a browser at a server rather than installing a full installation of FloreantPOS, which may not be possible.</span></p>
<p><span style="font-family:arial,helvetica,sans-serif;">Webswing is pretty great-- it integrates printing, clipboard, administrator "mirroring", SSL, etc.</span></p>
<p><span style="font-family:arial,helvetica,sans-serif;">To set up Webswing requires minimal computing skills. No special programming is required. Just basic installation and file-editing skills.</span></p>
<p><span style="font-family:arial,helvetica,sans-serif;">So, here's what you need to do...</span></p>
<p><span style="font-family:arial,helvetica,sans-serif;">NOTE: For this example, I have a username of "<strong><span style="font-family:courier new,courier,monospace;">fattire</span></strong>" so my installation of floreant is in <span style="font-family:courier new,courier,monospace;">/home/fattire/Desktop/active_floreantpos</span>-- in the instructions below, you should change <strong>fattire</strong> to whatever your Ubuntu username is.</span></p>
<ol>
<li><span style="font-family:arial,helvetica,sans-serif;">There are a few dependencies you want to make sure you have installed. Some of these will already have been installed when you ran my floreant_updater.sh script, but just be sure you have the rest by typing this command (this requires root permissions):<br />
<br />
<span style="font-family:courier new,courier,monospace;">sudo apt-get install </span></span><span style="font-family:courier new,courier,monospace;">xvfb libxext6 libxi6 </span><span style="font-family:courier new,courier,monospace;">libxrender1<br />
<br />
<span style="font-family:arial,helvetica,sans-serif;">(I think this is all the packages. Hopefully I didn't miss any but will update these instructions if I did.)</span></span><br />
</li>
<li><span style="font-family:arial,helvetica,sans-serif;">Download a <a href="http://builds.webswing.org/">recent build of Webswing</a>, and unzip it to your <span style="font-family:courier new,courier,monospace;">Desktop</span> to a folder you should call </span><span style="font-family: 'courier new', courier, monospace;">webview</span><span style="font-family:arial,helvetica,sans-serif;">. (Refer to <a href="http://jenkins.webswing.org/job/webswing%20master/doclinks/1/server/install/">these docs</a> if you need help for the next few sections.)</span><br />
</li>
<li><span style="font-family:arial,helvetica,sans-serif;">Inside, there's a file called <span style="font-family:courier new,courier,monospace;">start.sh</span>. I had to make a few modifications to get this to run "headlessly":<br />
<br />
Add this to the top:</span>
<p><span style="font-family:courier new,courier,monospace;">export DISPLAY=":0.0"</span></p>
<p><span style="font-family:courier new,courier,monospace;"># Start Xvfb<br />
if [ -f /usr/X11R6/bin/Xvfb ]; then<br />
/usr/X11R6/bin/Xvfb :1 -screen 0 1024x768x16<br />
fi</span></p>
<span style="font-family:arial,helvetica,sans-serif;">Next, change the <span style="font-family:courier new,courier,monospace;">HOME</span> variable to look like this. Change <span style="font-family:courier new,courier,monospace;">fattire</span> below to your username.</span><br />
<br />
<span style="font-family:courier new,courier,monospace;">export HOME=/home/<strong>fattire</strong>/Desktop/webswing</span><br />
<br />
<span style="font-family:arial,helvetica,sans-serif;">Finally, <span style="font-family:arial,helvetica,sans-serif;">comment out with <span style="font-family:courier new,courier,monospace;">#</span> (or remove) the following lines. They didn't seem to work for me and everything worked still worked without it. They start with:<br /><br />
<span style="font-family:courier new,courier,monospace;">if [ ! -z `command -v ldconfig` ]; then<br />
<br />
<span style="font-family:arial,helvetica,sans-serif;">and end with</span><br />
<br />
fi<br />
<br />
<span style="font-family:courier new,courier,monospace;"># See how we were called.</span></span></span></span></li>
<li>
<p>You will also need to make sure that <span style="font-family:courier new,courier,monospace;">start.sh</span> has the privileges to be run as a user. To do this, type:<br />
<br />
<span style="font-family:courier new,courier,monospace;">chmod +x start.sh</span><br />
<br />
<span style="font-family:arial,helvetica,sans-serif;">from the </span><span style="font-family:courier new,courier,monospace;">~/Desktop/webswing</span> <span style="font-family:arial,helvetica,sans-serif;">directory</span>.</p>
</li>
<li>
<p><span style="font-family:arial,helvetica,sans-serif;">Now that the <span style="font-family:courier new,courier,monospace;">start.sh</span> script is ready, let's add floreant to the list of apps via webswing's Web Interface. To do this, simply type:<br />
<br />
<span style="font-family:courier new,courier,monospace;">./start.sh start</span><br />
<br />
Now from any computer on your local network, go to a web browser and visit your Ubuntu device's IP address on port 8080 (the default). For example, if your Ubuntu machine is at 192.168.1.100, you would type <span style="font-family:courier new,courier,monospace;">http://192.168.1.100:8080</span> into your browser.<br />
<br />
Hopefully you will be greeted with a login. The default username is <strong>admin</strong> and password is <strong>pwd</strong>. You should change this at some future point.<br />
<br />
If you have problems logging in, again you can refer to <a href="http://jenkins.webswing.org/job/webswing%20master/doclinks/1/server/install/">here</a>. If <span style="font-family:courier new,courier,monospace;">start.sh</span> crashes, check the script-- you may have commented out the wrong lines (?) Or perhaps there is a dependency missing that you still need to install. Review the documentation for clues.<br />
<br />
Assuming you were able to log in, you can now follow the instructions on Webswing's <a href="http://webswing.org/2.4/#quick-start-guide">Quick Start Guide</a> for how to add FloreantPOS as a web app.<br />
<br />
To help you with this, here are the relevant settings that were added to my webswing.config file after I added floreant. You can use these values, but don't forget to change <strong>fattire</strong> to your own user name.</span><br />
<br />
(A BUNCH OF STUFF... THEN..)<br />
<span style="font-family:courier new,courier,monospace;"> }, {<br />
"name" : "Floreant",<br />
"icon" : "/home/<strong>fattire</strong>/Desktop/active_floreantpos/config/logo.png",<br />
"vmArgs" : "",<br />
"classPathEntries" : [ "/home/<strong>fattire</strong>/Desktop/active_floreantpos/floreantpos.jar", "/home/<strong>fattire</strong>/Desktop/active_floreantpos/lib/*jar" ],<br />
"homeDir" : "/home/<strong>fattire</strong>/Desktop/active_floreantpos",<br />
"theme" : "Murrine",<br />
"maxClients" : 20,<br />
"antiAliasText" : true,<br />
"swingSessionTimeout" : 300,<br />
"authorization" : false,<br />
"isolatedFs" : false,<br />
"debug" : false,<br />
"authentication" : false,<br />
"directdraw" : false,<br />
"allowDelete" : true,<br />
"allowDownload" : true,<br />
"allowUpload" : true,<br />
"allowJsLink" : true,<br />
"mainClass" : "com.floreantpos.main.Main",<br />
"args" : ""<br />
} ],<br />
<strong>(MORE STUFF)</strong></span><br />
<br />
<span style="font-family:arial,helvetica,sans-serif;"> Again, I am using the default installation directory <span style="font-family:courier new,courier,monospace;">~/Desktop/active_floreantpos</span> which is created by my script.</span><br />
</p>
</li>
<li>
<p><span style="font-family:arial,helvetica,sans-serif;">When everything is properly set up, you should be able to log in via </span><span style="font-family: 'courier new', courier, monospace;">http://192.168.1.100:8080<span style="font-family:arial,helvetica,sans-serif;"> and FloreantPOS will appear as an option which you can then run directly from the browser.</span></span><br />
</p>
</li>
<li>
<p><font face="arial, helvetica, sans-serif">Once you've got it all ready-- you can customize the settings-- add SSL for secure browser connections, create a dedicated page (See Webswing's README.txt file) to automatically start with FloreantPOS rather than go through the app menu, adjust the screen size in <span style="font-family:courier new,courier,monospace;">start.sh</span> (that is, </font><span style="font-family: 'courier new', courier, monospace;">/usr/X11R6/bin/Xvfb :1 -screen 0 1024x768x16)<span style="font-family:arial,helvetica,sans-serif;"> to better reflect the size of the tablet or virtual machine you want to use, etc.</span></span><br />
</p>
</li>
</ol>
<p><span style="font-family:arial,helvetica,sans-serif;"><strong><h3>STEP THREE: USE A DEDICATED APP TO ACCESS FLOREANT FROM ANDROID (OR iOS OR A PC OR WHATEVER)</h3></strong></span></p>
<p>While you can now simply access <span style="font-family: 'courier new', courier, monospace;">http://192.168.1.100:8080 <span style="font-family:arial,helvetica,sans-serif;">from a browser on your phone to access FloreantPOS, you will run into a few issues</span>:</span></p>
<ul>
<li><span style="font-family:arial,helvetica,sans-serif;">The URL bar at the top of the browser is kind of annoying and takes up valuable screen space.</span><br />
</li>
<li><span style="font-family:arial,helvetica,sans-serif;">The browser may or may not permit pinch-zooming and may not be scaled properly so that you get the full app on the screen. You don't want to have to slide your finger around everywhere to center the app or to find the area you want to touch. That sucks.</span></li>
</ul>
<p><span style="font-family:arial,helvetica,sans-serif;">My solution: an Android app to:</span></p>
<ol>
<li><span style="font-family:arial,helvetica,sans-serif;">It presents a full-screen <a href="http://developer.android.com/reference/android/webkit/WebView.html">WebView</a> and loads it with the Floreant Web App. Doesn't include a URL bar, menu bar, or any other "bells and whistles" Just starts and immediately presents the interface.</span><br /></li>
<li><span style="font-family:arial,helvetica,sans-serif;">Can be used to automatically scale to to "full screen" so you get the whole page scaled to the dimensions of the tablet/phone.</span><br/></li>
<li><span style="font-family:arial,helvetica,sans-serif;">You can change the viewport preferences and URL-related stuff in the settings</span></li>
</ol>
<p span style="font-family:arial,helvetica,sans-serif;">Couldn't be more basic.</p>
<p style="font-family:arial,helvetica,sans-serif;"><b>Update:</b> Per request, I've posted my app source code (released under the GPL). It's called HipPOS <a href="https://www.github.com/fat-tire/hippos">and you can grab source code here</a>. I did make a lot of the UI changes that I figured would be useful.</p>
<p><span style="font-family:arial,helvetica,sans-serif;"><strong>CAVEATS</strong>:</span></p>
<ul>
<li style="font-family:arial,helvetica,sans-serif;">Smaller tablets and phones with an effective resolution of less than 1024 width may notice that the main floreantPOS window "cuts off" because it's bigger than the view area. I'm not sure, but this may be related to <a href="https://github.com/fat-tire/floreantpos/blob/4ba271160024355cc1f096d7b3648c194145bca2/src/com/floreantpos/main/PosWindow.java#L156">code that makes the minimum size 1024x724</a>. You may want to play with the floreant source code (the latest is on sourceforge.net, tho I mirrored a non-up-to-date version <a href="https://github.com/fat-tire/floreantpos">here</a>.
<li><span style="font-family:arial,helvetica,sans-serif;">I have not tested to see how well this scales or performs under any kind of load.</span></li>
<li><span style="font-family:arial,helvetica,sans-serif;">The above does not use SSL or encryption of any kind across the network. SSL is available in webswing however. I just didn't play with it yet. The HipPOS app ignores SSL errors, which I think/hope may allow self-signed certificates to work.</span></li>
<li><span style="font-family:arial,helvetica,sans-serif;">This example uses default passwords. You want to change those!</span></li>
<li><span style="font-family:arial,helvetica,sans-serif;">My changes to <span style="font-family:courier new,courier,monospace;">start.sh</span> are probably not always needed and certainly not complete as Xvfb is never killed so multiple versions may hang around. There's probably a better solution, but these steps are just what I did quickly to get a proof-of-concept going</span></li>
<li><span style="font-family:arial,helvetica,sans-serif;">I see there is a 2.6 version of webswing in development, which may work differently.</span></li>
</ul>
</body>
</html>