add client docu: config and concepts
authorkonrad <konrad@6e3c4bff-ac9f-4ac1-96c5-d2ea494d3e33>
Mon, 14 Mar 2011 21:19:02 +0000 (21:19 +0000)
committerkonrad <konrad@6e3c4bff-ac9f-4ac1-96c5-d2ea494d3e33>
Mon, 14 Mar 2011 21:19:02 +0000 (21:19 +0000)
git-svn-id: https://silmor.de/svn/softmagic/smoke/trunk@743 6e3c4bff-ac9f-4ac1-96c5-d2ea494d3e33

doc/client/concepts.html
doc/client/config-office.png [new file with mode: 0644]
doc/client/config-profile.png [new file with mode: 0644]
doc/client/config-settings.png [new file with mode: 0644]
doc/client/config.html
doc/client/config1.png [new file with mode: 0644]
doc/client/config2.png [new file with mode: 0644]
doc/client/config3.png [new file with mode: 0644]
doc/client/config4.png [new file with mode: 0644]
doc/client/index.html
doc/server.html

index 071c85d..28e3008 100644 (file)
@@ -4,13 +4,95 @@
 <body>
 <h1>Magic Smoke Concepts Documentation</h1>
 
+<h2>Architecture</h2>
+
+MagicSmoke consists of two main components: the server and the client. The server stores all events, tickets, orders, etc. The client provides access to it.<p>
+
+There are two main lanes of access to the server - one for customers through a web browser and one for the theater itself through the specialized client.<p>
+
+<table>
+<tr>
+ <td bgcolor="#c0c0c0">Theater Access
+ <td bgcolor="#a0a0a0">Customer Access
+</tr>
+<tr><td height="5px" colspan="2" bgcolor="#000000"/></tr>
+<tr>
+ <td bgcolor="#c0c000">Client
+ <td bgcolor="#ffff80">Browser
+ </tr>
+<tr><td bgcolor="#e0e0e0" colspan="2" align="center"><i>Network (HTTP)</i></tr>
+<tr>
+ <td bgcolor="#4040ff">machine.php<br>(Theater Interface)
+ <td bgcolor="#c0c0ff">index.php<br>(Customer Interface)
+</tr>
+<tr><td bgcolor="#80ff80" colspan="2">MagicSmoke Server / Apache / Database</tr>
+</table><p>
+
+<h2>Events and Tickets</h2>
+
+Selling seats for events is what MagicSmoke was created for. In terms of MagicSmoke an event has the following properties:
+
+<ul>
+<li>a title that tells the audience what the programme is called
+<li>an artist who performs it
+<li>a room in which it is performed
+<li>a start and end time and date, that tells us when it is performed
+<li>a capacity that tells us how many tickets can be sold for the event, initially this is copied from the room's settings, but can be changed for each event
+<li>a description that is shown to customers on the web page
+<li>prices that tell us the price of tickets and how many of each category can be sold
+</ul>
+
+Tickets belong to a specific event and enable the owner to enter the audience of an event. A Ticket has these properties:
+
+<ul>
+<li>the event it belongs to
+<li>the price category it belongs to
+<li>its price, which is normally copied from the category, but can be changed by privileged users
+<li>a ticket ID that uniquely identifies the ticket
+<li>the order in which it was sold (see below)
+</ul>
+
+The amount of tickets for an event is limited by several factors:
+
+<ul>
+<li>the capacity of the event is the absolute upper limit, no more than this can be sold
+<li>the capacity of the ticket's price category
+</ul>
+
+<h2>Orders and Vouchers</h2>
+
+MagicSmoke stores customers with names and potentially many addresses. Customers can be created from the client or by the customer him/herself through the web interface.<p>
+
+An order is generated whenever tickets are ordered, sold, or given away for free. The order connects tickets with customers and tracks the payment of those. The difference between an order and a straight sale is that the "order" is not paid and shipped when created, while the "sale" is paid and shipped right from the start.<p>
+
+Vouchers can be bought by customers and in return they can be used to pay for orders. Like tickets, each voucher has a unique ID that identifies it.
+
+<h2>Templates and Printing</h2>
+
+Templates are the base of everything that can be stored in OpenOffice files or that can be printed.<p>
+
+MagicSmoke has two ways of printing: tickets and vouchers are printed directly from the client. Other documents are created in OpenDocument format and then stored, opened with OpenOffice, or printed through OpenOffice.
+
+<h2>Login, Users, Hosts, and Profiles</h2>
+<a name="auth"/>
+
+MagicSmoke uses the multi-layer login. It authenticates both the client host and the user. This is to make sure that users only connect from hosts that belong to the correct theater, it is also possible to restrict some users to fewer hosts.<p>
+
+The login process performs the following checks:
+
 <ol>
-<li>Architecture (Server, Browser, Client)
-<li>Events
-<li>Orders and Tickets
-<li>Printing
-<li>Users, Hosts, Profiles
-<li>Scripting
+<li>the client authenticates the server using the SSL certificate
+<li>the server authenticates the client using its host name and key
+<li>the server authenticates the user by name and password
+<li>the server checks that the user is allowed to log in from that host
 </ol>
 
+If any of those checks fails the login is denied.<p>
+
+<b>Profiles</b> are used by the client to link a specific server together with a specific host setting and other settings to be used with this server.
+
+<h2>Scripting</h2>
+
+MagicSmoke attempts to execute specific scripts at various times, like client startup, the printing of tickets, or the creation of order bills. Scripts are written in the Javascript dialect of Qt.
+
 </html>
\ No newline at end of file
diff --git a/doc/client/config-office.png b/doc/client/config-office.png
new file mode 100644 (file)
index 0000000..38e2096
Binary files /dev/null and b/doc/client/config-office.png differ
diff --git a/doc/client/config-profile.png b/doc/client/config-profile.png
new file mode 100644 (file)
index 0000000..8998a2e
Binary files /dev/null and b/doc/client/config-profile.png differ
diff --git a/doc/client/config-settings.png b/doc/client/config-settings.png
new file mode 100644 (file)
index 0000000..cdac75f
Binary files /dev/null and b/doc/client/config-settings.png differ
index b208845..1870ded 100644 (file)
@@ -4,4 +4,91 @@
 <body>
 <h1>Magic Smoke Client Configuration</h1>
 
+From the configuration dialog you can edit profiles and change all global settings that are independent of profiles and running connections.
+
+<h2>Profiles</h2>
+<a name="profiles"/>
+
+Each profile describes how connections to a specific <a href="../server.html">server</a> is made and what security settings are used for this profile. A profile has a name that is visible in the title bar of the session window.<p>
+
+A profile is created by chosing "Profile" - "New Profile..." from the menu.<p>
+
+<img src="config1.png"/><p>
+
+In the picture above you can see the connection settings. The URL must contain the complete path to the <tt>machine.php</tt> file - the MagicSmoke client forces this URL to start with "https://". The settings below are used if you have to connect through a web proxy - check the "Proxy" checkbox to activate proxy support.<p>
+
+The profile that is displayed bold is the default profile. The default profile is the one that is pre-selected when MagicSmoke is started.<p>
+
+The Profile menu allows you to manipulate profiles:
+<ul>
+<li><b>New Profile...</b> - creates a new empty profile.</li>
+<li><b>Delete Profile</b> - deletes the currently selected profile.</li>
+<li><b>Rename Profile...</b> - gives the currently selected profile a new name.</li>
+<li><b>Clone Profile...</b> - creates a new profile by copying the currently selected profile.</li>
+<li><b>Make Default Profile</b> - marks the currently selected profile as default profile.</li>
+</ul>
+
+<img src="config-profile.png"/><p>
+
+<a name="hostkey"/>
+
+Below you see the Authentication tab, which defines how the MagicSmoke client <a href="concepts.html#auth">authenticates</a> to the server:<br/>
+
+<ul>
+<li><b>Hostname</b> - the name under which the client identifies itself to the server</li>
+<li><b>Hostkey</b> - the key that the client uses to identify itself. The key should be a hexa-decimal number.</li>
+<li><b>Default Username</b> - the user name that is pre-selected in the login window. Leave this field empty if you do not want a pre-selection.</li>
+</ul><p>
+
+You can manipulate host keys through the "Profile" menu:<p>
+
+<ul>
+<li><b>Generate Host Key...</b> - generates a new key for the host.</li>
+<li><b>Export Host Key...</b> - exports the name and key as a file that can be imported in other clients or through the <a href="../server.html#admin_php">admin interface</a> of the server.</li>
+<li><b>Import Host Key...</b> - imports a key file.</li>
+</ul>
+
+<img src="config2.png"/><p>
+
+The "SSL Exceptions" tab (below) can be used to allow the use of self-signed certificates for MagicSmoke servers. Normally the SSL engine used by MagicSmoke insists that the server's connection is properly authenticated down to a root certificate known to the operating system. To configure these connections click the "Probe Server" - MagicSmoke will either tell you that the connection was successful or what errors occurred. Check the finger print - if it matches accept the errors - from now on MagicSmoke will compare all errors it encounters with the recorded finger print and stored errors and accepts the connection if they match.<p>
+
+<img src="config3.png"/><p>
+
+The "Scripting" tab (below) defines whether any scripts are performed by the client and which source of scripts are accepted.<p>
+
+<img src="config4.png"/><p>
+
+<b>Server side scripts</b>: it is possible to store scripts on the server. If allowed, MagicSmoke downloads those scripts and executes them at specific times. Since scripts can access any part of the program and even the underlying system, you should allow this only for servers that you trust.<p>
+
+<b>Built in scripts</b>: MagicSmoke comes with some very basic scripts built in. Use these if you do not allow any other scripts.<p>
+
+<b>User local scripts</b>: scripts can also be installed locally - either to overide the server scripts or to use a known good version copied from the server. The <b>User script path</b> setting tells MagicSmoke where to find those local scripts.<p>
+
+<h2>Other Settings</h2>
+
+The "Settings" menu allows you to change settings that are shared by all profiles.<p>
+
+<img src="config-settings.png"/><p>
+
+Using the <b>Language...</b> menu item you can chose between all installed translations - the new translation becomes active after a restart of MagicSmoke.<p>
+
+The <b>OpenOffice.org Settings...</b> allow you to define how MagicSmoke interfaces with OpenOffice or <a href="http://www.libreoffice.org/download/">LibreOffice</a> version 3.x. OpenOffice is used to create and print reports, bills, etc.<p>
+
+Available options are:<p>
+
+<ul>
+<li><b>Path to Executable</b> - the program that is being called. Per default "soffice" is called and expected to be in the systems PATH.</li>
+<li><b>Printer</b> - the printer that is being used when printing through OpenOffice.<li>
+<li><b>Always confirm...</b> - if checked MagicSmoke will ask the user which printer is to be used with the one configured above being pre-selected. If unchecked MagicSmoke prints on that printer without asking.</li>
+<li><b>Save printed files</b> - asks the user to chose a file name to store a copy of any file that is being printed.</li>
+<li><b>Always open as Read-Only</b> - asks OpenOffice to open files in read-only mode instead of read-write mode.</li>
+<li>Automatically open...</b> - when saving files also opens them.</li>
+</ul>
+
+<img src="config-office.png"/><p>
+
+The <b>Set Default Label Font...</b> allows you to chose a fall-back font for labels (tickets and vouchers) if they do not contain their own font or the font inside them cannot be interpreted by the MagicSmoke.<p>
+
+The <b>Set Application Style...</b> menu item allows you to change how MagicSmoke looks.<p>
+
 </html>
\ No newline at end of file
diff --git a/doc/client/config1.png b/doc/client/config1.png
new file mode 100644 (file)
index 0000000..df8f129
Binary files /dev/null and b/doc/client/config1.png differ
diff --git a/doc/client/config2.png b/doc/client/config2.png
new file mode 100644 (file)
index 0000000..05746a4
Binary files /dev/null and b/doc/client/config2.png differ
diff --git a/doc/client/config3.png b/doc/client/config3.png
new file mode 100644 (file)
index 0000000..9a6898c
Binary files /dev/null and b/doc/client/config3.png differ
diff --git a/doc/client/config4.png b/doc/client/config4.png
new file mode 100644 (file)
index 0000000..0f2fc1e
Binary files /dev/null and b/doc/client/config4.png differ
index 0278413..6764aa5 100644 (file)
@@ -13,6 +13,7 @@ This section of the documentation describes how to use the dedicated Magic Smoke
 <li>Creating Events and Inventory
 <li>Selling and Shipping
 <li>User Administration
+<li>Templates
 <li>Scripting
 </ol>
 
index 205bfc2..3567090 100644 (file)
@@ -131,6 +131,7 @@ These options configure the timeouts of cookies, what features are available to
 
 
 <h2>Database Initialization</h2>
+<a name="admin_php"/>
 
 Open a browser and direct it to admin.php in your MagicSmoke installation (usually something like <tt>http://localhost/magicsmoke/admin.php</tt>).
 
@@ -142,7 +143,7 @@ Click the create database button.
 
 Create an initial administrator user using the form at the bottom of the page.<p>
 
-Open the client and create a host key for it - upload this host key using the admin form and allow the initial administrator to use any host.<p>
+Open the client and <a href="client/config.html#hostkey">create a host key</a> for it - upload this host key using the admin form and allow the initial administrator to use any host.<p>
 
 Done.