write votes tutorial

[goeddea]

should

• give a full overview of a working application
• cover all important concepts
• be stand-alone: a reader can come from anywhere and get all the necessary information to understand what's happening just from reading the tutorial.
• give links to help with deeper understanding of the concepts
• be for anybody, irrespective of the language used (regarding the concepts)
• offer a choice to see backend implementations in common languages

  structure:

  what does the application do (gives the user a framework for why we are doing things)

• send votes to a backend
• receive votes updates from backend
• keeps displayed votes in sync across all instances
• can also reset votes

  The concepts behind it

Sseparate concepts and implementations: no need to understand two things at once + key concepts are covered twice in the tutorial.

• messages exchanged via a single protocol
• no direct connection between frontends and backends - all routed
• so: connections between frontend / backend and router
• symmetric: all participants have the same rights. frontend and backend are functions, not a technical distinction
• two messaging patterns:
• RPC - call a procedure. here: vote, request vote reset
• PUbSub - express interest in a topic and receive events for this. here: vote updates, vote reset

to illustrate:

• we want to explain a sequence of events
• the easiest version: allow the user to click through the sequence for this, i.e. a user-operated slideshow. This makes it clear what happens after what without requiring huge amounts of space. Implementation is simple enough.

  The actual code:

choose your weapon:

• Allow the user to choose his language(s) when he comes to the specific code, i.e. pick a frontend and a backend technology, and the rest of the tutorial shows the relevant information
• frontend: we're realistically only talking about the browser here (the frontend needs a graphical represenation), so the choice is backend:
  • JS/browser
  • JS/node
  • Python
  • PHP
  • Erlang
  • C++ we should at least have JS/node, Python + PHP as these are realistic, established options, plus JS/browser since the differences are minor and this is an interesting and important point to make.
• Establishing a connection
  • URL
  • realm
  • options - not shown here, but link to documentation
  • the counterpart: show the transport configuration on crossbar for this
• Registering a procedure
• calling a procedure
• subscribing to a topic
• publishing to a topic

Try to include enough information here about the messaging patterns that a reader who's skipped to this section still has a chance to understand things, and that others get a quick repetition to really bring the concepts home.

along the way OR finishing remarks and further thoughts:

• RPC vs. PubSub - use what feels right for a praticular use case. You could implement procedure calls via PubSub: Subscrive to specific topic, execute function on event, then publish the result. Do the 1-to-1 coupling e.g. via additional unique topic sent with the original publish. This feels wrong. Otherwise: do what works best for your use case.
• Using a call return vs. subscription to event: Here the subscription is used since this is the easiest way: a single mechanism for updates, independently of whether these are based on user action in the instance or external event. This works here because there is just a single reaction to vote updates: change the displayed vote count. In more complex UIs, it will often be necessary to do additional things, e.g. close a dialog from which the call was issued, remove highlighting, add highlighting depending on whether the event was locally caused or externally… In these cases, the suggested pattern is: send the required data in the call return, process this in the caller. IN the callee, exclude the caller from the publish.
• Sequence of subscribe and initial calls for data: we do not want gaps in our data. this means the subscription should be requested before we call for initial data. In order to avoid strange behavior, it may be necessary to additionally use a flag here: set to false initially, and do not process subscription events if this is false. Set to true once the initial data set has been received (and, possibly, processed).

further reading:

• get started right away • is Crossbar right for me: • features list • application scenarios • demos • WAMP background • WAMP + Autobahn + Crossbar - how are they connected • documentations • Crossbar • Autobahn libraries • WAMP spec

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/4244255-write-votes-tutorial?utm_campaign=plugin&utm_content=tracker%2F462544&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F462544&utm_medium=issues&utm_source=github).

[goeddea]

reopen (migrating back from https://github.com/crossbario/crossbardocs/issues/29)