diff --git a/.gitignore b/.gitignore index d7bb865cb34775dc08bf9caa6caa8519008c9d7f..5003f73cc338171ef21b699e8a10f990d157fb75 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +/doc/*.pdf /.doc_plantuml /.support /.support_plantuml diff --git a/CODING.md b/doc/CODING.md similarity index 71% rename from CODING.md rename to doc/CODING.md index 8b499af70ad075105aa96ec083f09219060b46a0..2da8713423e7fcc07672759222488991b1221767 100644 --- a/CODING.md +++ b/doc/CODING.md @@ -72,107 +72,6 @@ DELETE * HTML Code: <button type="button" class="record-delete" data-sip={{SIP}} ><span class="glyphicon glyphicon-trash"></span></button> - -USER INTERFACE -============== - -Button status -------------- -* Form modified: - * Buttons enabled: Save, Close, New, Delete - * Button disable: - - -* Form not modified: - * Buttons enabled: Close, New, Delete - * Button disabled: Save - -Save Button ------------ - -* User presses the button - * Reset all validation states - * Client validates HTML Form - * Form is submitted to server - * Success: - * Show message provided by server - * Current formelements and data will be reloaded. - * Process server reponse 'redirect': - * 'client': No redirect. - * 'no': No redirect. - * 'url': Redirect to URL - * Failure: Happens on communication errors, if data validation fails, form actions fails or saving data fails. - * Show error message. - * Client: Ignore server reponse 'redirect'. Client stays on current page. - - -Close Button ------------- -* User presses the button - * Form not modified by user: Client redirects to previous page. - * Form modified by user: Ask User 'You have unsaved changes. Do you want to close?' - * Yes: Client redirects to previous page. - * No: Client stays on current page. - * Save & Close: - * Client reset all validation states - * Client validates HTML Form - * Client submits form to server. - * Success: Process server response 'redirect': - * 'client': Client shows previous page. - * 'no': No redirect. - * 'url': Redirect to URL - * Failure: Happens on communication errors, if data validation fails, form actions fails or saving data fails. - * Show error message. - * Client: No redirect. Ignore server reponse 'redirect'. - -Delete Button: Main record --------------------------- -* User presses the button. Ask User 'Do you really want to delete the record? - * Yes: - * Delete record on server. - * Process server reponse 'redirect': - * 'client': Client redirects to previous page. - * 'no': Error message. - * 'url': Redirect to URL - * No: - * Client does not delete record on server. - * No redirect. Client stays on current page. - -New Button ----------- -* User presses the button - * Form not modified by user: Client redirects to href url. - * Form modified by user: Ask User 'You have unsaved changes. Do you want to save first?' - * Yes: - * Client reset all validation states - * Client validates HTML Form - * Form is submitted to server - * Success: - * Client: Ignore server reponse 'redirect'. Client redirects to href url. - * Failure: Happens on communication errors, if data validation fails, form actions fails or saving data fails. - * Show error message. - * Client: Ignore server reponse 'redirect'. Client stays on current page. - * No: - * Client does not save the modified record. - * Client redirects to href url. - * Cancel: - * Client does not save the modified record. - * Client stays on current page. - - -File Handling: Upload ---------------------- -* No previous uploaded file present - 1. User presses the Browse button - 1. User selects file - 1. File is uploaded to qfq immediately - 1. Browse button gets disabled and hidden - 1. File delete button is shown - 1. User cancels file selection - 1. no action -* Previous uploaded file present - 1. User deletes file - 1. File delete button gets disabled and hidden - 1. Browse button gets enabled and displayed Form Build (load) ................. @@ -314,4 +213,4 @@ Checkbox </label> </div> - \ No newline at end of file + diff --git a/doc/HTML.md b/doc/HTML.md new file mode 100644 index 0000000000000000000000000000000000000000..d7d3266f03759c60187b40e35e44d6675f1b4863 --- /dev/null +++ b/doc/HTML.md @@ -0,0 +1,39 @@ +# HTML + +This document explains the HTML markup used by QFQ. + +## Hooks + +Hooks are used on by the Client to gather information required for +asynchronous requests and to add predefined event handlers to HTML Elements. + + +### form.data-toggle="validator" + +Adding the attribute `data-toggle="validator"` to a `<form>` element, +enables the Bootstrap Validator on that HTML Form. + + +### .data-sip + +Asynchronous requests require to pass a SID to the Server. Elements +triggering an asynchronous request, may gather the SIP from the +`data-sip` attribute assigned to the HTML Form Element. + + +### .class="record-delete" + +HTML Form Buttons having the class `record-delete` set, will get an +`onclick` handler attached by `QfqNS.QfqRecordList`. Each `<button>` +also requires an `data-sip` attribute. + + +### .data-load="" + +HTML Form Elements having the attribute `data-load`, will trigger a +call to `api/load.php` upon change. + +### id="save-button" +### id="close-button" +### id="delete-button" +### id="form-new-button" diff --git a/LAYOUT.md b/doc/LAYOUT.md similarity index 100% rename from LAYOUT.md rename to doc/LAYOUT.md diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..b9d13ff192becbd391749e0c62edcdffb0d78717 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,9 @@ +SOURCES = CODING.md HTML.md PROTOCOL.md UI.md LAYOUT.md +PDFDOCS = $(patsubst %.md,%.pdf,$(SOURCES)) + +all: $(PDFDOCS) + +.md.pdf: + pandoc -o $@ $< + +.SUFFIXES: .md .pdf diff --git a/PROTOCOL.md b/doc/PROTOCOL.md similarity index 100% rename from PROTOCOL.md rename to doc/PROTOCOL.md diff --git a/doc/UI.md b/doc/UI.md new file mode 100644 index 0000000000000000000000000000000000000000..23764da72cf07cadcaaaf554474eae20116921d4 --- /dev/null +++ b/doc/UI.md @@ -0,0 +1,102 @@ +USER INTERFACE +============== + +Button states +------------- +If the HTML Form has no modifications, the `Close`, `New` and `Delete` +buttons are enabled. The `Save` button is disabled. + +If the HTML Form has modifications, the `Save`, `Close`, `New`, and +`Delete` button is enabled. No button is disabled. + + +Save Button +----------- + +* User presses the Save button + 1. Reset all validation states + 1. Client validates HTML Form + 1. Form is submitted to server + * Success: + 1. Show message provided by server + 1. Current formelements and data will be reloaded. + 1. Process server reponse 'redirect': + * 'client': No redirect. + * 'no': No redirect. + * 'url': Redirect to URL + * Failure: Happens on communication errors, if data validation + fails, form actions fails or saving data fails. + 1. Show error message. + 1. Client: Ignore server reponse 'redirect'. Client stays on current page. + + +Close Button +------------ +* User presses the Close button + 1. Form not modified by user: Client redirects to previous page. + 1. Form modified by user: Ask User 'You have unsaved changes. Do you want to close?' + * Yes: Client redirects to previous page. + * No: Client stays on current page. + * Save & Close: + 1. Client reset all validation states + 1. Client validates HTML Form + 1. Client submits form to server. + * Success: Process server response 'redirect': + * 'client': Client shows previous page. + * 'no': No redirect. + * 'url': Redirect to URL + * Failure: Happens on communication errors, if data validation + fails, form actions fails or saving data fails. + * Show error message. + * Client: No redirect. Ignore server reponse 'redirect'. + +Delete Button: Main record +-------------------------- +* User presses the button. Ask User 'Do you really want to delete the record? + * Yes: + * Delete record on server. + * Process server reponse 'redirect': + * 'client': Client redirects to previous page. + * 'no': Error message. + * 'url': Redirect to URL + * No: + * Client does not delete record on server. + * No redirect. Client stays on current page. + +New Button +---------- +* User presses the button + * Form not modified by user: Client redirects to href url. + * Form modified by user: Ask User 'You have unsaved changes. Do you want to save first?' + * Yes: + * Client reset all validation states + * Client validates HTML Form + * Form is submitted to server + * Success: + * Client: Ignore server reponse 'redirect'. Client redirects to href url. + * Failure: Happens on communication errors, if data validation fails, form actions fails or saving data fails. + * Show error message. + * Client: Ignore server reponse 'redirect'. Client stays on current page. + * No: + * Client does not save the modified record. + * Client redirects to href url. + * Cancel: + * Client does not save the modified record. + * Client stays on current page. + + +File Handling: Upload +--------------------- +* No previous uploaded file present + 1. User presses the Browse button + 1. User selects file + 1. File is uploaded to qfq immediately + 1. Browse button gets disabled and hidden + 1. File delete button is shown + 1. User cancels file selection + 1. no action +* Previous uploaded file present + 1. User deletes file + 1. File delete button gets disabled and hidden + 1. Browse button gets enabled and displayed +