View source for Backend Ajax protocol

= Discussion =

There should be a standard JSON protocol between the LS backend and Ajax calls to check for errors, permissions and if the user still is logged in. A suggestion would be to wrap <code>$.ajax</code> in a function that checks this for you, like <code>LS.ajax</code>.

All server Ajax calls must return a JSON in the following format:

<syntaxhighlight lang="javascript">
{
  type: int,
  result: mixed,
  error: {code: int, message: string},
  loggedIn: boolean,
  hasPermission: boolean,
}
</syntaxhighlight>

Of course there needs to be server side support for this protocol, too, with helper functions to output correct JSON code, e.g. <code>Ajax::outputResult</code> or <code>Ajax::outputError($code, $message)</code>.

Preferably, the function should be able to show an error if server throws 500.

== Message types ==

{|
! Type !! Fields !! Description
|-
| notloggedin || - || User is not logged in; the login form should appear in a modal and then continue with the action
|-
| nopermission || - || No permission
|-
| success || success : string || Show success message
|-
| error || error : string || Show error message
|-
| custom || result : mixed || Custom action, meaning a supplied Javascript function will take care of the response from the server, e.g. feeding HTML to a modal body. BUT: Maybe we could have a message type "modal" which sends modal title, body and footer?
|}

= Backbone =

Since Javascript library [http://backbonejs.org/ Backbone] might be used in the future, it would be nice to know how they handle stuff like this.

Some questions:

* Would we need to duplicate the model code in both backend and frontend? Yes, we would need to code validation in both Backbone model and Yii model. <i>Or</i>, we don't use the module system at all from Backbone, and just send submit data to server (serialized forms).
* How much of the CRUD will happen on client? All of it. REST is used to sync client to server.
* How much would backbone replace Yii and things generated with Gii?
* Would all views be put on the client? I'd prefer if we didn't split views between server and client. Here using Mustache would be a clear advantage, since it easily can be used from both Yii and Backbone. Or we can configure Twig to look like Underscore templates. [[User:Olle|Olle]] ([[User talk:Olle|talk]]) 20:43, 28 September 2016 (CEST)
* LS will probably never be a single-page application, which means Backbone will be used on a per-module or per-page basis, to make Ajax operations more smooth.
* It would be interesting to make a plugin to showcase how Backbone can be used inside LS.

== Template engines ==

=== [http://underscorejs.org/ Underscore] ===

Example:

<syntaxhighlight lang="html">
<script id='my-template' type='text/template'>
  <strong><%= name %></strong> - <%= age %>
</script>
</syntaxhighlight>

== Logger ==

We need a front-end logger, and there's a couple of libraries to Backbone that does this, e.g. [https://github.com/stream7/backbone-logger this one].

== Learning material ==

* http://backbonejs.org/
* [https://www.youtube.com/watch?v=2ERWc0RT3qY Youtube tutorial]
* [https://addyosmani.com/backbone-fundamentals/ Free book]

= Class diagrams =

[[File:jsonoutput.png]]

[https://drive.google.com/file/d/0B2zfh04EPg7FU3BTek83YjlWTjQ/view?usp=sharing Source.]

= Implementation =

A first prototype of the backend classes can be seen [https://github.com/LimeSurvey/LimeSurvey/blob/global_participants/application/helpers/admin/ajax_helper.php here]. Instead of a helper, this class can actually be put into LSYiiController, making it available to all controllers in LS.

Example:

<syntaxhighlight lang="php">
public function indexAction()
{
  \ls\ajax\AjaxHelper::outputSucces(gT('Success!'));
}
</syntaxhighlight>

Using <code>LS.ajax</code> instead of <code>$.ajax</code> will automatically take care of login and success/failure messages, provided you use the ajax helper above to output json from PHP.