joy_ussd_engine 0.1.0 → 0.1.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +5 -1
- data/Gemfile.lock +42 -0
- data/README.md +76 -70
- data/images/lifecycle.jpg +0 -0
- data/joy_ussd_engine.gemspec +7 -2
- data/lib/joy_ussd_engine/menu.rb +1 -1
- data/lib/joy_ussd_engine/version.rb +1 -1
- data/pkg/joy_ussd_engine-0.1.1.gem +0 -0
- data/pkg/joy_ussd_engine-0.1.2.gem +0 -0
- metadata +5 -5
- data/.DS_Store +0 -0
- data/.gitignore +0 -8
- data/.rubocop.yml +0 -13
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 87daa4c0dae57919366d4454695275f33052d7505412c80d19cf571e85e1ea91
|
|
4
|
+
data.tar.gz: 7d0c6af6ff5792d2bbabc646ab0c5d720ae72eafbe0138dcf7ff9846e097065b
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: eb4c5b98ce92119a64af3a8983f03282e653fc1728f1c003f61e35a515dade0bf8187f4016cf95103ccdd0222e43f742143d39088f065e08072ba666f4c54c3e
|
|
7
|
+
data.tar.gz: 74e3b79758b858bbaece5fc524cee1ba3a3eee99e0322013cf16d331f2a9533f961ddd5cc24722f8140e1a0424d9f00e15cdfe37e1358a0ea1c1bdf66670bdfd
|
data/CHANGELOG.md
CHANGED
data/Gemfile.lock
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
PATH
|
|
2
|
+
remote: .
|
|
3
|
+
specs:
|
|
4
|
+
joy_ussd_engine (0.1.2)
|
|
5
|
+
will_paginate (~> 3.3.0)
|
|
6
|
+
|
|
7
|
+
GEM
|
|
8
|
+
remote: https://rubygems.org/
|
|
9
|
+
specs:
|
|
10
|
+
ast (2.4.2)
|
|
11
|
+
parallel (1.21.0)
|
|
12
|
+
parser (3.0.2.0)
|
|
13
|
+
ast (~> 2.4.1)
|
|
14
|
+
rainbow (3.0.0)
|
|
15
|
+
rake (13.0.6)
|
|
16
|
+
regexp_parser (2.2.1)
|
|
17
|
+
rexml (3.2.5)
|
|
18
|
+
rubocop (1.20.0)
|
|
19
|
+
parallel (~> 1.10)
|
|
20
|
+
parser (>= 3.0.0.0)
|
|
21
|
+
rainbow (>= 2.2.2, < 4.0)
|
|
22
|
+
regexp_parser (>= 1.8, < 3.0)
|
|
23
|
+
rexml
|
|
24
|
+
rubocop-ast (>= 1.9.1, < 2.0)
|
|
25
|
+
ruby-progressbar (~> 1.7)
|
|
26
|
+
unicode-display_width (>= 1.4.0, < 3.0)
|
|
27
|
+
rubocop-ast (1.11.0)
|
|
28
|
+
parser (>= 3.0.1.1)
|
|
29
|
+
ruby-progressbar (1.11.0)
|
|
30
|
+
unicode-display_width (1.8.0)
|
|
31
|
+
will_paginate (3.3.1)
|
|
32
|
+
|
|
33
|
+
PLATFORMS
|
|
34
|
+
-darwin-20
|
|
35
|
+
|
|
36
|
+
DEPENDENCIES
|
|
37
|
+
joy_ussd_engine!
|
|
38
|
+
rake (~> 13.0)
|
|
39
|
+
rubocop (~> 1.7)
|
|
40
|
+
|
|
41
|
+
BUNDLED WITH
|
|
42
|
+
2.2.21
|
data/README.md
CHANGED
|
@@ -86,7 +86,7 @@ class MyController < ApplicationController
|
|
|
86
86
|
skip_before_action :verify_authenticity_token
|
|
87
87
|
|
|
88
88
|
def create
|
|
89
|
-
joy_ussd_engine = JoyUssdEngine::Core.new(ussd_params, Transformers::HubtelTransformer, start_point: Ussd::Menus::StartMenu, end_point: Ussd::Menus::EndMenu)
|
|
89
|
+
joy_ussd_engine = JoyUssdEngine::Core.new(ussd_params, Ussd::Transformers::HubtelTransformer, start_point: Ussd::Menus::StartMenu, end_point: Ussd::Menus::EndMenu)
|
|
90
90
|
response = joy_ussd_engine.process
|
|
91
91
|
render json: response, status: :created
|
|
92
92
|
end
|
|
@@ -99,12 +99,12 @@ end
|
|
|
99
99
|
|
|
100
100
|
The `JoyUssdEngine::Core.new` class takes the following parameters.<a id="params"></a>
|
|
101
101
|
|
|
102
|
-
| Parameter
|
|
103
|
-
|
|
|
104
|
-
| params
|
|
105
|
-
| [data_transformer](#
|
|
106
|
-
| [start_point](#menu)
|
|
107
|
-
| [end_point](#menu)
|
|
102
|
+
| Parameter | Type | Description |
|
|
103
|
+
| ------------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
|
104
|
+
| params | hash | Params coming from a post end point in a rails controller |
|
|
105
|
+
| [data_transformer](#datatransformer) | class | A class to transform the incoming and outgoing request between a particular provider and `JoyUssdEngine` |
|
|
106
|
+
| [start_point](#menu) | class | Points to a menu that starts the application. This menu is the first menu that loads when the app starts |
|
|
107
|
+
| [end_point](#menu) | class | This menu will terminate the ussd session if a particular provider (`data_transformer`) returns true in the `app_terminator` method. |
|
|
108
108
|
|
|
109
109
|
### Generators
|
|
110
110
|
|
|
@@ -117,7 +117,7 @@ The rails terminal is very powerful and we can utilize it to generate menus easi
|
|
|
117
117
|
|
|
118
118
|
### DataTransformer
|
|
119
119
|
|
|
120
|
-
A data transformer transforms the incoming request and outgoing response between a particular provider and the `JoyUssdEngine` so they can effectively communicate
|
|
120
|
+
A data transformer transforms the incoming request and outgoing response between a particular provider and the `JoyUssdEngine` so they can effectively communicate with each other. The `JoyUssdEngine` can accept any request object but there are two required fields that needs to be present for it to work properly. The required fields are `session_id` and `message`. This is why the `DataTransformer` is needed to convert the request so it can provide this two required fields (`session_id`, `message`).
|
|
121
121
|
|
|
122
122
|
#### Methods
|
|
123
123
|
|
|
@@ -134,7 +134,7 @@ A data transformer transforms the incoming request and outgoing response between
|
|
|
134
134
|
When using `hubtel` we need to convert the `hubtel` request into what the `JoyUssdEngine` expects with the `request_params` method. Also we need to convert the response back from `JoyUssdEngine` to `hubtel` with the `response` and `release` methods. With this approach we can easily extend the `JoyUssdEngine` to target multiple providers like (Twilio, Telegram, etc) with ease. The `app_terminator` returns a boolean and terminates the app when a particular condition is met(For example: On whatsapp the user sends a message with text `end` to terminate the app)
|
|
135
135
|
|
|
136
136
|
```ruby
|
|
137
|
-
class HubtelTransformer < JoyUssdEngine::DataTransformer
|
|
137
|
+
class Ussd::Transformers::HubtelTransformer < JoyUssdEngine::DataTransformer
|
|
138
138
|
# Transforms request payload between hubtel and our application
|
|
139
139
|
# The session_id and message fields are required so we get them from hubtel (session_id: params[:Mobile] and message: params[:Message]).
|
|
140
140
|
# And we pass in other hubtel specific params like (ClientState: params[:ClientState], Type: params[:Type])
|
|
@@ -183,19 +183,19 @@ end
|
|
|
183
183
|
|
|
184
184
|
### Menu
|
|
185
185
|
|
|
186
|
-
Menus are simply the views for our application. They contain the code for rendering the text
|
|
186
|
+
Menus are simply the views for our application. They contain the code for rendering the text that display on the user's device. Also they contain the business logic for your app.
|
|
187
187
|
|
|
188
188
|
#### Menu Properties
|
|
189
189
|
|
|
190
|
-
| Properties
|
|
191
|
-
|
|
|
192
|
-
| context | object
|
|
193
|
-
| field_name\* | string
|
|
194
|
-
| menu_text\* | string
|
|
195
|
-
| error_text | string
|
|
196
|
-
| skip_save | boolean
|
|
197
|
-
| menu_items | array <{title: '',
|
|
198
|
-
| field_error | boolean
|
|
190
|
+
| Properties | Type | Description |
|
|
191
|
+
| ------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
192
|
+
| @context | object | Provides methods for setting and getting state values |
|
|
193
|
+
| @field_name\* | string | The name for a particular input field. This name can be used to later retrieve the value the user entered in that field. (**Required**) |
|
|
194
|
+
| @menu_text\* | string | The text to display to the user. (**Required**) |
|
|
195
|
+
| @error_text | string | If there is an error you will have to set the error message here. (**Optional**) |
|
|
196
|
+
| @skip_save | boolean | If set to true the user input will not be saved. **Default: false** (**Optional**) |
|
|
197
|
+
| @menu_items | array <{title: '', route: JoyUssdEngine::Menu}> | Stores an array of menu items with their corresponding routes. |
|
|
198
|
+
| @field_error | boolean | If set to true it will route back to the menu the error was caught in for the user to input the correct values. |
|
|
199
199
|
|
|
200
200
|
#### Lifecycle Methods
|
|
201
201
|
|
|
@@ -209,25 +209,25 @@ Menus are simply the views for our application. They contain the code for render
|
|
|
209
209
|
|
|
210
210
|
#### Render Methods
|
|
211
211
|
|
|
212
|
-
| Methods | Parameters | Description
|
|
213
|
-
| ------------ | ---------- |
|
|
214
|
-
| joy_response | Menu | This method takes a single argument (which is a class that points to the next menu) and is used to render out
|
|
215
|
-
| joy_release | none | This method renders
|
|
216
|
-
| load_menu | Menu | This method takes a single argument (which is a class that points to the next menu) and is used with the Routing and Paginating Menus to render out menu items. |
|
|
212
|
+
| Methods | Parameters | Description |
|
|
213
|
+
| ------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
214
|
+
| joy_response | Menu | This method takes a single argument (which is a class that points to the next menu) and is used to render out the text stored in the `@menu_text` variable to the user. |
|
|
215
|
+
| joy_release | none | This method renders the text in the `@menu_text` variable to the user and ends the users session |
|
|
216
|
+
| load_menu | Menu | This method takes a single argument (which is a class that points to the next menu) and is used with the [Routing](#routing-menus) and [Paginating](#paginatemenu) Menus to render out menu items. |
|
|
217
217
|
|
|
218
218
|
#### Other Methods
|
|
219
219
|
|
|
220
|
-
| Methods | Description
|
|
221
|
-
| ----------------- |
|
|
222
|
-
| show_menu | Returns
|
|
223
|
-
| get_selected_item | Gets the
|
|
224
|
-
| raise_error | Takes an error message as an arguments and
|
|
225
|
-
| has_selected? | Checks if the user has selected an item
|
|
220
|
+
| Methods | Description |
|
|
221
|
+
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
222
|
+
| show_menu | Returns the menu text to be rendered out. This method is used with only [Routing](#routing-menus) and [Paginating](#paginatemenu) Menus |
|
|
223
|
+
| get_selected_item | Gets the users selection from the `@menu_items` array |
|
|
224
|
+
| raise_error | Takes an error message as an arguments and renders the message to the user before ending the user's session |
|
|
225
|
+
| has_selected? | Checks if the user has selected an item from the `@menu_items` array |
|
|
226
226
|
|
|
227
227
|
#### Create a menu
|
|
228
228
|
|
|
229
229
|
```ruby
|
|
230
|
-
class Menus::MainMenu < JoyUssdEngine::Menu
|
|
230
|
+
class Ussd::Menus::MainMenu < JoyUssdEngine::Menu
|
|
231
231
|
def on_validate
|
|
232
232
|
# use this method to validate the user's input
|
|
233
233
|
|
|
@@ -264,7 +264,7 @@ class Menus::MainMenu < JoyUssdEngine::Menu
|
|
|
264
264
|
# Render ussd menu here
|
|
265
265
|
|
|
266
266
|
# the joy_response renders out the ussd menu and takes the class of the next menu to route to as an argument.
|
|
267
|
-
joy_response(Menus::NextMenu)
|
|
267
|
+
joy_response(Ussd::Menus::NextMenu)
|
|
268
268
|
end
|
|
269
269
|
end
|
|
270
270
|
```
|
|
@@ -280,30 +280,35 @@ When the user enters a value which is not the string `"john doe"` an error will
|
|
|
280
280
|
#### Execution Order of Lifecycle Methods
|
|
281
281
|
|
|
282
282
|
- before_render
|
|
283
|
-
***
|
|
284
|
-
This is the first method that gets executed. It is used for querying the db and handling the business logic of our application. This method also is used to set the text (`menu_text`) to be rendered and the input name (`field_name`) for the current menu.
|
|
285
|
-
- on_validate
|
|
286
283
|
|
|
287
284
|
***
|
|
288
285
|
|
|
289
|
-
This
|
|
286
|
+
This is the first method that gets executed. It is used for querying the db and handling the business logic of our application. This method also is used to set the text (`@menu_text`) to be rendered and the input name (`@field_name`) for the current menu.
|
|
290
287
|
|
|
291
288
|
- on_error
|
|
292
289
|
|
|
293
290
|
***
|
|
294
291
|
|
|
295
|
-
This is the next method that gets executed and it is used to set error messages. It will only be executed if the
|
|
292
|
+
This is the next method that gets executed and it is used to set error messages. It will only be executed if the `@field_error` value is set to true.
|
|
296
293
|
|
|
297
294
|
- render
|
|
298
295
|
|
|
299
296
|
***
|
|
300
297
|
|
|
301
|
-
This method is used for rendering out the menu by using the text stored in the
|
|
298
|
+
This method is used for rendering out the menu by using the text stored in the `@menu_text` variable. There are only three methods that should be used in the render method. Which are [joy_release](#render-methods), [joy_response](#render-methods), and [load_menu](render-methods).
|
|
302
299
|
|
|
303
300
|
- after_render
|
|
301
|
+
|
|
304
302
|
***
|
|
303
|
+
|
|
305
304
|
Use this method to do any other business logic after the menu has been rendered out and awaiting user response.
|
|
306
305
|
|
|
306
|
+
- on_validate
|
|
307
|
+
|
|
308
|
+
***
|
|
309
|
+
|
|
310
|
+
This method will be executed when the user submits a response. We use this method to validate the user's input and set an error_message to display when there is an error. Normally we will set `@field_error` value to true and store the error message in `@error_text`. Then we can later access the error_message in the `on_error` lifecycle method and append the error message to `@menu_text` so it will be rendered out to the user.
|
|
311
|
+
|
|
307
312
|
#### Execution Order Diagram
|
|
308
313
|
|
|
309
314
|
The Diagram below shows how these methods are executed
|
|
@@ -312,7 +317,7 @@ The Diagram below shows how these methods are executed
|
|
|
312
317
|
|
|
313
318
|
#### Get Http Post Data
|
|
314
319
|
|
|
315
|
-
We can access the post request data coming from the rails controller in any menu with the
|
|
320
|
+
We can access the post request data coming from the rails controller in any menu with the `@context` object. The `@context` object can be used to access post data by reading values from the `params` hash of a post request. This hash consist of the `session_id`, `message` and any other additional data returned by the `request_params` method in the [DataTransformer](#datatransformer) class.
|
|
316
321
|
|
|
317
322
|
```ruby
|
|
318
323
|
# Just call @context.params[key] to access a particular value coming from a post request made available to our app through the DataTransformer.request_params method.
|
|
@@ -322,7 +327,7 @@ We can access the post request data coming from the rails controller in any menu
|
|
|
322
327
|
|
|
323
328
|
#### Saving and Accessing Data
|
|
324
329
|
|
|
325
|
-
We can save and access data in any menu with the
|
|
330
|
+
We can save and access data in any menu with the `@context` object. The `@context` object has two methods `set_state` and `get_state` which are used for saving and retrieving data. The saved data will be destroyed once the user session ends or is expired and it is advisable to persist this data into a permanent storage like a database if you will need it after the user session has ended.
|
|
326
331
|
|
|
327
332
|
```ruby
|
|
328
333
|
# Just call @context.set_state(key: value) to set a key with a particular value
|
|
@@ -332,9 +337,9 @@ We can save and access data in any menu with the `context` object. The `context`
|
|
|
332
337
|
@context.get_state[:selected_book]
|
|
333
338
|
```
|
|
334
339
|
|
|
335
|
-
Also by default any menu that has the
|
|
340
|
+
Also by default any menu that has the `@field_name` variable set. Will automatically save the users input with a key matching the string stored in the `@field_name` variable.
|
|
336
341
|
|
|
337
|
-
**Note:** However if the
|
|
342
|
+
**Note:** However if the `@skip_save` variable is set to true the user input will not be store for that particular menu. By default this value is false.
|
|
338
343
|
|
|
339
344
|
```ruby
|
|
340
345
|
# This stores the name of the input field for this menu
|
|
@@ -355,11 +360,11 @@ We can throw an error with a message and terminate the user session any where in
|
|
|
355
360
|
return raise_error("Sorry something went wrong!")
|
|
356
361
|
```
|
|
357
362
|
|
|
358
|
-
There is also another way to handle errors without ending or terminating the user session. We can use the `on_validate` lifecycle method to validate user input and when there is an error we set the
|
|
363
|
+
There is also another way to handle errors without ending or terminating the user session. We can use the `on_validate` lifecycle method to validate user input and when there is an error we set the `@field_error` variable to true and the `@error_text` variable to include the error message.
|
|
359
364
|
|
|
360
|
-
Then in the `on_error` lifecycle method we can append the
|
|
365
|
+
Then in the `on_error` lifecycle method we can append the `@error_text` variable to the `@menu_text` variable so it displays the error when render an output to the user.
|
|
361
366
|
|
|
362
|
-
**Note:** The `on_error` method will only be invoke if the
|
|
367
|
+
**Note:** The `on_error` method will only be invoke if the `@field_error` variable is set to true.
|
|
363
368
|
|
|
364
369
|
[View the example code on error handling here](#create_menu)
|
|
365
370
|
|
|
@@ -369,7 +374,7 @@ You can show a list of menu items with their corresponding routes. When the user
|
|
|
369
374
|
When the user selects a menu that is not in the list an error is displayed to the user and the user session wil be terminated.
|
|
370
375
|
|
|
371
376
|
```ruby
|
|
372
|
-
class Menus::InitialMenu < JoyUssdEngine::Menu
|
|
377
|
+
class Ussd::Menus::InitialMenu < JoyUssdEngine::Menu
|
|
373
378
|
|
|
374
379
|
def before_render
|
|
375
380
|
# Implement before call backs
|
|
@@ -378,8 +383,8 @@ class Menus::InitialMenu < JoyUssdEngine::Menu
|
|
|
378
383
|
|
|
379
384
|
# Store a list of menu items with their routes
|
|
380
385
|
@menu_items = [
|
|
381
|
-
{title: 'Make Payments', route: Menus::MakePayments},
|
|
382
|
-
{title: 'View Transaction', route: Menus::ViewTransaction}
|
|
386
|
+
{title: 'Make Payments', route: Ussd::Menus::MakePayments},
|
|
387
|
+
{title: 'View Transaction', route: Ussd::Menus::ViewTransaction}
|
|
383
388
|
]
|
|
384
389
|
|
|
385
390
|
# Show menu items on screen with the show_menu method.
|
|
@@ -390,8 +395,8 @@ class Menus::InitialMenu < JoyUssdEngine::Menu
|
|
|
390
395
|
def render
|
|
391
396
|
# Render ussd menu here
|
|
392
397
|
|
|
393
|
-
# Use
|
|
394
|
-
# get_selected_item automatically listens to user inputs and passes the selected menu into load_menu method
|
|
398
|
+
# Use the `load_menu` method to load the menus on screen
|
|
399
|
+
# The `get_selected_item` method automatically listens to user inputs and passes the selected menu into the `load_menu` method
|
|
395
400
|
load_menu(get_selected_item)
|
|
396
401
|
end
|
|
397
402
|
end
|
|
@@ -401,10 +406,10 @@ This will be rendered out when this menu is executed
|
|
|
401
406
|
|
|
402
407
|
|
|
403
408
|
|
|
404
|
-
If the `Menus::ViewTransaction` has a structure like this.
|
|
409
|
+
If the `Ussd::Menus::ViewTransaction` has a structure like this.
|
|
405
410
|
|
|
406
411
|
```ruby
|
|
407
|
-
class Menus::ViewTransaction < JoyUssdEngine::Menu
|
|
412
|
+
class Ussd::Menus::ViewTransaction < JoyUssdEngine::Menu
|
|
408
413
|
|
|
409
414
|
def before_render
|
|
410
415
|
# Implement before call backs
|
|
@@ -419,11 +424,11 @@ class Menus::ViewTransaction < JoyUssdEngine::Menu
|
|
|
419
424
|
end
|
|
420
425
|
```
|
|
421
426
|
|
|
422
|
-
When the user enters 2 in the `Menus::InitialMenu` menu then the following will be rendered and the user session will be terminated.
|
|
427
|
+
When the user enters 2 in the `Ussd::Menus::InitialMenu` menu then the following will be rendered and the user session will be terminated.
|
|
423
428
|
|
|
424
429
|
|
|
425
430
|
|
|
426
|
-
The `Menus::ViewTransaction` menu uses the `joy_release` method to render out the text stored in the `@menu_text` variable and ends the user session.
|
|
431
|
+
The `Ussd::Menus::ViewTransaction` menu uses the `joy_release` method to render out the text stored in the `@menu_text` variable and ends the user session.
|
|
427
432
|
|
|
428
433
|
### PaginateMenu
|
|
429
434
|
|
|
@@ -434,12 +439,12 @@ A `PaginateMenu` has all the properties and methods in a `Menu` in addition to t
|
|
|
434
439
|
|
|
435
440
|
A `PaginateMenu` has the following properties in addition properties in [Menu](#menu).
|
|
436
441
|
|
|
437
|
-
| Properties
|
|
438
|
-
|
|
|
439
|
-
| paginating_items | array <any> | Stores an array of items to paginate on a particular menu. |
|
|
440
|
-
| items_per_page | integer | The number of items to show per page. **Default: 5** |
|
|
441
|
-
| back_key | string | A string holding the input value for navigating back. **Default: '0'** |
|
|
442
|
-
| next_key | string | A string holding the input value for navigating forward. **Default: '#'** |
|
|
442
|
+
| Properties | Type | Description |
|
|
443
|
+
| ----------------- | ----------- | ------------------------------------------------------------------------- |
|
|
444
|
+
| @paginating_items | array <any> | Stores an array of items to paginate on a particular menu. |
|
|
445
|
+
| @items_per_page | integer | The number of items to show per page. **Default: 5** |
|
|
446
|
+
| @back_key | string | A string holding the input value for navigating back. **Default: '0'** |
|
|
447
|
+
| @next_key | string | A string holding the input value for navigating forward. **Default: '#'** |
|
|
443
448
|
|
|
444
449
|
#### PaginateMenu Methods
|
|
445
450
|
|
|
@@ -453,7 +458,7 @@ A `PaginateMenu` has the following properties in addition properties in [Menu](#
|
|
|
453
458
|
#### PaginateMenu Example
|
|
454
459
|
|
|
455
460
|
```ruby
|
|
456
|
-
class Menus::Books < JoyUssdEngine::PaginateMenu
|
|
461
|
+
class Ussd::Menus::Books < JoyUssdEngine::PaginateMenu
|
|
457
462
|
|
|
458
463
|
def before_render
|
|
459
464
|
# Implement before call backs
|
|
@@ -470,23 +475,24 @@ A `PaginateMenu` has the following properties in addition properties in [Menu](#
|
|
|
470
475
|
{title: "Design Patterns In C#", item: {id: 8}}
|
|
471
476
|
]
|
|
472
477
|
|
|
473
|
-
# The paginate
|
|
478
|
+
# The `paginate` method returns a list of paginated items for the current page when it is called
|
|
474
479
|
paginated_list = paginate
|
|
475
480
|
|
|
476
|
-
# In a PaginateMenu the show_menu
|
|
481
|
+
# In a PaginateMenu the `show_menu` method takes a list and two optional named parameter values (title,key).
|
|
477
482
|
|
|
478
483
|
# The title shows the page title for the menu.
|
|
479
484
|
|
|
480
|
-
# The key stores the key of the hash which contains the text to be rendered
|
|
485
|
+
# The key stores the key of the hash which contains the text to be rendered for each list item.
|
|
481
486
|
|
|
482
487
|
# If the key is not set the paginating_items is treated as a string and rendered to the user.
|
|
488
|
+
|
|
483
489
|
# eg: @paginating_items = ["Data Structures","Excel Programming","Economics","Big Bang","Democracy Building","Python for Data Scientist","Money Mind","Design Patterns In C#"]
|
|
484
490
|
|
|
485
491
|
@menu_text = show_menu(paginated_list, title: 'My Books', key: 'title')
|
|
486
492
|
|
|
487
493
|
# In other to select a paginating item we have to wrap the selection logic in an if has_selected? block to prevent some weird errors.
|
|
488
494
|
if has_selected?
|
|
489
|
-
# the get_selected_item is used to get the selected item from the paginating
|
|
495
|
+
# the get_selected_item is used to get the selected item from the paginating list
|
|
490
496
|
selected_book = get_selected_item
|
|
491
497
|
|
|
492
498
|
# We save the selected book so we can access later
|
|
@@ -498,14 +504,14 @@ A `PaginateMenu` has the following properties in addition properties in [Menu](#
|
|
|
498
504
|
# Render ussd menu here
|
|
499
505
|
|
|
500
506
|
# The load_menu function points to a menu to load when a book is selected.
|
|
501
|
-
load_menu(Menus::ShowBook)
|
|
507
|
+
load_menu(Ussd::Menus::ShowBook)
|
|
502
508
|
end
|
|
503
509
|
end
|
|
504
510
|
```
|
|
505
511
|
|
|
506
|
-
To use a `PaginateMenu` we have to store the items to be paginated in the
|
|
512
|
+
To use a `PaginateMenu` we have to store the items to be paginated in the `@paginating_items` variable. Then we call the `paginate` method and store the result in a variable (`paginated_list`). We can now pass the variable (`paginated_list`) into the `show_menu` method and specify a `title` for the page if we have any. The `show_menu` method can also accept a `key` which is used to get the key containing the string to be rendered in a paginating_item. If the `key` is left blank the `@paginating_items` are treated as strings and rendered automatically.
|
|
507
513
|
|
|
508
|
-
In order to get the item the user selected we have to wrap the selection login in an `if has_selected?` block to prevent some weird errors, then we can access the selected item with the `get_selected_item` method.
|
|
514
|
+
In order to get the item the user has selected we have to wrap the selection login in an `if has_selected?` block to prevent some weird errors, then we can access the selected item with the `get_selected_item` method.
|
|
509
515
|
|
|
510
516
|
The following screenshots shows the paginating menu when it's first rendered.
|
|
511
517
|
|
|
@@ -515,10 +521,10 @@ When the user enters '#' we move to the next page in the list.
|
|
|
515
521
|
|
|
516
522
|
|
|
517
523
|
|
|
518
|
-
In the next menu (`Menus::ShowBook`) we have code that looks like this.
|
|
524
|
+
In the next menu (`Ussd::Menus::ShowBook`) we have code that looks like this.
|
|
519
525
|
|
|
520
526
|
```ruby
|
|
521
|
-
class Menus::ShowBook <
|
|
527
|
+
class Ussd::Menus::ShowBook < JoyUssdEngine::Menu
|
|
522
528
|
def before_render
|
|
523
529
|
# Implement before call backs
|
|
524
530
|
book = @context.get_state[:selected_book]
|
data/images/lifecycle.jpg
CHANGED
|
Binary file
|
data/joy_ussd_engine.gemspec
CHANGED
|
@@ -22,9 +22,14 @@ Gem::Specification.new do |spec|
|
|
|
22
22
|
|
|
23
23
|
# Specify which files should be added to the gem when it is released.
|
|
24
24
|
# The `git ls-files -z` loads the files in the RubyGem that have been added into git.
|
|
25
|
-
spec.files = Dir
|
|
26
|
-
`git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
|
|
25
|
+
spec.files = Dir['**/*'] do
|
|
26
|
+
`git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features|images)/}) }
|
|
27
27
|
end
|
|
28
|
+
|
|
29
|
+
# spec.files = `git ls-files -z`.split("\x0").reject do |f|
|
|
30
|
+
# f.match(%r{^(test|spec|features)/})
|
|
31
|
+
# end
|
|
32
|
+
|
|
28
33
|
spec.bindir = "exe"
|
|
29
34
|
spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
|
|
30
35
|
spec.require_paths = ["lib"]
|
data/lib/joy_ussd_engine/menu.rb
CHANGED
|
@@ -43,7 +43,7 @@ module JoyUssdEngine
|
|
|
43
43
|
@context.set_state({"#{@current_client_state}_show_menu_initiation".to_sym => nil})
|
|
44
44
|
set_previous_state
|
|
45
45
|
@context.current_menu = @current_client_state = next_menu
|
|
46
|
-
@context.
|
|
46
|
+
@context.load_from_paginate_menu(next_menu)
|
|
47
47
|
end
|
|
48
48
|
end
|
|
49
49
|
|
|
Binary file
|
|
Binary file
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: joy_ussd_engine
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.1.
|
|
4
|
+
version: 0.1.2
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Caleb Mantey
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: exe
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2022-03-
|
|
11
|
+
date: 2022-03-17 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: will_paginate
|
|
@@ -34,12 +34,10 @@ executables: []
|
|
|
34
34
|
extensions: []
|
|
35
35
|
extra_rdoc_files: []
|
|
36
36
|
files:
|
|
37
|
-
- ".DS_Store"
|
|
38
|
-
- ".gitignore"
|
|
39
|
-
- ".rubocop.yml"
|
|
40
37
|
- CHANGELOG.md
|
|
41
38
|
- CODE_OF_CONDUCT.md
|
|
42
39
|
- Gemfile
|
|
40
|
+
- Gemfile.lock
|
|
43
41
|
- LICENSE.txt
|
|
44
42
|
- README.md
|
|
45
43
|
- Rakefile
|
|
@@ -72,6 +70,8 @@ files:
|
|
|
72
70
|
- lib/joy_ussd_engine/paginate_menu.rb
|
|
73
71
|
- lib/joy_ussd_engine/session_manager.rb
|
|
74
72
|
- lib/joy_ussd_engine/version.rb
|
|
73
|
+
- pkg/joy_ussd_engine-0.1.1.gem
|
|
74
|
+
- pkg/joy_ussd_engine-0.1.2.gem
|
|
75
75
|
homepage: https://github.com/Caleb-Mantey/joy_ussd_engine
|
|
76
76
|
licenses:
|
|
77
77
|
- MIT
|
data/.DS_Store
DELETED
|
Binary file
|
data/.gitignore
DELETED
data/.rubocop.yml
DELETED