Consumers

Communication Between the Consumers

There are two consumers for each participant in a poker session in order to communicate between the server and the client. They talk to each other using messages in JSON format, which always contain the name of the event they want to trigger at the recipient(s) and any additional data they want to send alongside with the message. The consumers on both sides provide a method you can use to send an event.

Sample message:

{
  "type": "send_json",
  "event": "story_changed",
  "data": {
    "id": 2,
    "story_label": "Poker 2: Create Screenshots",
    "description": "<h1>HTML Ipsum</h1>\r\n\r\n<p><strong>Pellentesque habitant</strong>...",
    "votes": {
      "3": [
        {
          "id": 1,
          "name": "JohnDoe"
        }
      ],
      "5": [
        {
          "id": 2,
          "name": "MaxMustermann"
        }
      ]
    }
  }
}

Both consumers contain an attribute, defining which events will be handled, which can be easily expanded to add additional features in the future. See the Server-Side or Client-Side consumers for more information on how these attributes are defined.

Note

Consumers in the frontend can only talk to their corresponding consumer on the backend, whereas the consumer on the backend can either message all the front end consumers or only send messages to their counterpart.

Server-Side

class PokerConsumer(*args, **kwargs)[source]

Bases: JsonWebsocketConsumer

Consumer responsible for the communication between the moderator’s and voter’s websockets.

Use the provided send_event method to send events to the client-side consumers. Events are strings signaling a specific thing occurred. Any event listeners can then differentiate between different events and perform special reactions based on their name.

These are the events sent by the server by default

Event Name

Targets

Data

story_points_submitted

All consumers

 
{
    # The amount of points the story should
    # be set to
    "story_points": 5
}

story_changed

All consumers or a single consumer

 
{
    # The ID of the story to display
    "id": 1,
    # The label of the story
    "story_label": "Poker 2: Create Screenshots",
    # The description of the story
    "description": "<h1>HTML Ipsum</h1>\r\n\r\n<p><strong>Pellentes...",
    # Object containing the story points
    # and their voters
    "votes": {
        # A list of users who voted for
        # this amount of story points
        "3": [
            {
                # The ID of the user
                "id": 1,
                # The name of the user
                "name": "John Doe"
            },
            {
                "id": 2,
                "name": "Max Mustermann"
            }
        ],
        "5": [
            {
                "id": 3,
                "name": "Thomas"
            }
        ]
    }
}

poker_session_ended

All consumers

 
{
    # The URL to which the participants
    # of the poker session should be
    # redirected when the session ends
    "poker_session_end_redirect_url": "/poker/"
}

participants_changed

All consumers

 
{
    # A list of all participants
    "participants": [
        {
            # The ID of the user
            "id": 1,
            # The name of the user
            "name": "John Doe"
        },
        {
            "id": 2,
            "name": "Max Mustermann"
        }
    ],
}

Expand the commands dictionary to respond to custom events.

commands: Dict[str, Dict[str, Any]]

This dictionary maps the events to another dictionary which has exactly two keys.

  • 'method' determines which method should be called to handle the data (e.g. self.reset_requested). Its value can be any callable. Any data passed along with the event will be passed into the callable as keyword arguments.

  • 'required_permission' restricts which users can respond to this event. Its value is either a Django permission string (e.g. MODERATE_PERMISSION) which will be used to evaluate the user’s permission via user.has_perm(required_permission) to see whether they are allowed to respond to the event or None if no permission is required.

poker_session

Return the planning_poker session corresponding to the websocket’s url.

Returns:

The planning_poker session corresponding to the websocket’s url.

connect()[source]

Accept the connection from a websocket.

disconnect(status_code)[source]

Remove self from the current group.

receive_json(content: Dict, **kwargs)[source]

Call the given method with its arguments. A log entry is made and no method is executed, if the user doesn’t have the required permission.

Parameters:

  • content – A dict containing the command and additional arguments. For example: ‘{‘event’: ‘foo’, ‘data’: data}’

  • kwargs – Additional keyword arguments.

send_event(event: str, send_to_group: bool = True, **data: Dict)[source]

Send an event with the given data either to the channel or to the whole group.

Parameters:

  • event – The name of the event which should be sent.

  • send_to_group – Flag whether the event should be sent to the whole group or not. Default True.

  • data – The data which should be sent along the event.

next_story_requested(story_id: Optional[int] = None)[source]

Set the planning_poker session’s active story and send all necessary data to the websockets.

Parameters:

story_id – The id of the story which should become the active story.

reset_requested()[source]

Remove all votes from the currently active story.

set_story_points(story_points: int)[source]

Set the story’s story points in the database.

Parameters:

story_points – The points which the story should have.

vote_submitted(choice: str)[source]

Update or create the vote for the user with their choice for the current story and broadcast it to all users.

Parameters:

choice – The choice for the story’s points the user made.

send_active_story_information(send_to_group: bool = True)[source]

Dispatch an Event containing the story’s information.

Parameters:

send_to_group – Flag whether the event should be sent to the whole group or not. Default True.

end_poker_session()[source]

Dispatch an Event which ends the planning_poker session.

heartbeat_received()[source]

Update the ‘last seen’ timestamp.

participants_changed(message: Dict)[source]

Dispatch an event containing a list of all participants.

Parameters:

message – The message contains information about the planning_poker session’s active participants.

MODERATE_PERMISSION = 'planning_poker.moderate'

Moderators will have this permission.

VOTE_PERMISSION = 'planning_poker.vote'

Voters will have this permission.

Client-Side

class BaseConsumer(container, websocketUrl)

Construct a BaseConsumer with the given parameters.

Arguments:

  • container (Element) – A DOM element containing all other needed elements.

  • websocketUrl (string) – The url to the websocket to which should be connected.

The BaseConsumer and its subclass on the client-side function similarly to the PokerConsumer on the server-side. The same things that were said about the server-side consumer also apply to the client-side consumers. Use sendEvent to send an event to the server and expand commands to respond to custom events.

commands: Object

This Object contains the event names as attributes and their corresponding values are the function which should be used to handle the data. The data object will be passed as an argument to the handler function.

BaseConsumer.processMessage(message)

Call the method given by the object with the additional data.

Arguments:

  • message (Object) – The message containing the event and data.

BaseConsumer.sendMessage(event, data)

Send a message to the websocket with the given event and data.

Arguments:

  • event (string) – The event which should be triggered on the server’s consumer.

  • data (Object) – An object containing the necessary data to process the message.

class PokerConsumer(container, websocketUrl, userId)

Construct a PokerConsumer with the given parameters.

Arguments:

  • container (Element) – A DOM element containing all other needed elements.

  • websocketUrl (string) – The url to the websocket to which should be connected.

  • userId (string) – The user’s id in the database.

These are the events sent by the client by default

Event Name

Data

next_story_requested

 
{
    # The ID of the requested story
    "story_id": 1
}

points_submitted

 
{
    # The amount of points the story should be set to
    "story_points": "5"
}

vote_submitted

 
{
    # The story points the voter voted for
    "choice": "3"
}

reset_requested

 
# Signals the server that the votes should be reset
{}

heartbeat

 
# Signals the server that the participant still partakes in
# the poker session
{}
PokerConsumer.endPokerSession(data)

End the Poker session by redirecting to the url specified by the event data.

Arguments:

  • data (Object) – Containing the url to which the user should be redirected.

PokerConsumer.hasUserVoted(votes)

Return whether the user’s id appears in the list of users who have already voted.

Arguments:

  • votes (Object) – Containing information about every choice that has votes + who voted for them.

Returns:

boolean – Return whether the user’s id appears in the list of users who have already voted.

PokerConsumer.nextStoryRequested(id)

Request the next story from the websocket.

PokerConsumer.resetRequested()

Request a reset of all votes.

PokerConsumer.storyChanged(data)

Update the displayed story information and voting results and select the choice for voters who have already voted.

Arguments:

  • data (Object) – Containing information about the story and votes.

PokerConsumer.storyPointsSubmitted(data)

Add a badge next to the story with the submitted story points.

Arguments:

  • data (object) – Containing the amount of the submitted story points.

PokerConsumer.submitChoice(choice)

Send a message to the websocket containing the voter’s choice.

Arguments:

  • choice (String) – Containing the voter’s choice.

PokerConsumer.submitStoryPoints(choice)

Send a message to the websocket containing the chosen amount of story points and request the next story from the server.

Arguments:

  • choice (String) – Containing the voter’s choice.

PokerConsumer.updateParticipantsList(data)

Update the displayed list of participants.

Arguments:

  • data (Object) – Containing a list of all participants and their permissions display.

PokerConsumer.updateResults(votes)

Change the VoteOverview’s content to display the given votes.

Arguments:

  • votes (Object) – Containing information about every choice that has votes + who voted for them.

PokerConsumer.updateStoryInformation(label, description)

Update the displayed title and description and reset the overlay.

Arguments:

  • label (string) – The story’s label.

  • description (string) – The story’s description rendered with html elements.