Drupal - Build a Mobile App Game to Learn Words from Another Language

In this tutorial we'll explore how to make a simple mobile application game with DrupalGap for a Drupal 7 website. Our game will help us learn words in another langauge.

We'll use Drupal to manage our words and their translations. Since Drupal comes with a default content type called Article, we'll use that for our words.

language-game-controls.png

1. Download and Install Drupal (in English)

• https://drupal.org/documentation/install

2. Enable Required Core Modules (included in Drupal Core)

• Locale
• Content translation

3. Enable Required Contrib Modules

• Title (https://drupal.org/project/Title)
• Entity Translation (https://drupal.org/project/entity_translation)
• DrupalGap (https://drupal.org/project/drupalgap)

4. Add Language

• Administration -> Configuration -> Regional and language
• admin/config/regional/language

For my game, I want to learn Vietnamese words. However, choose whichever language you'd like to learn words for, then click the 'Add language' button.

• Administration -> Configuration -> Regional and language -> Languages
• admin/config/regional/language/add

language-add.png

5. Enable URL Detection and Selection

• Administration -> Configuration -> Regional and language -> Languages -> Detection and Selection
• admin/config/regional/language/configure

Under 'Content language detection', check the 'Enabled' checkbox next to the URL detection method:

language-detection.png

Please note, the screen shot above does NOT have the checkbox checked, but you must CHECK the box, before hitting 'Save settings'.

6. Make Article Node Titles Translatable

• Administration -> Structure -> Content types -> Article -> Manage Fields
• admin/structure/types/manage/article/fields

Click the 'replace' link under the 'Operations' column for the 'Title' field. Then check the 'Replace title with a field instance' checkbox and click the 'Save settings' button.

language-replace-title.png

Please note, the screen shot above does NOT have the checkbox checked, but you must CHECK the box, before hitting 'Save settings'.

7. Make Article Nodes Translatable

• Administration -> Structure -> Content types -> Article
• admin/structure/types/manage/article

Go to 'Publishing options' and select the 'Enabled, with field translation' radio button, then hit the 'Save content type' button.

language-article-multilingual.png

8. Create Word to Translate

• Content -> Add content
• node/add/article

It seems natural that our first word to learn would be "Hello", so let's enter that into the Title field on the Create Article Node form:

language-title.png

We'll skip all the other fields for now (tags, body, image, language, etc), then go ahead and save your new node.

9. Translate Word

Click the 'Translate' tab when viewing your newly created node.

language-node-translate-tabe.png

Click the 'add' link under the 'Operations' column to add a translation for your secondary language. Then add the translation for "Hello" in the title field, then click the 'Save' button.

language-title-translated.png

For this example, the word "Hello" in Vietnamese is "Xin chào". Where did I get the translation? Good question. My wife is Vietnamese. Also, my daughter is 10 months old (at the time of writing this), so I need to get prepared for any multi lingual back talk :) If you don't have your own in-house translator, try Google Translate.

• http://translate.google.com/

10. View Translated Word

To view the translated word, we navigate to the node, then insert the language code at the front of the path, for example:

• http://language.tylerfrankenstein.com/node/1 (English)
• http://language.tylerfrankenstein.com/vi/node/1 (Vietnamese)

language-translated-view.png

Review step #5 to see the language detection and selection settings that make the above translated link possible.

11. Create a View to Return a Random Word (Article)

Our mobile application will need to be able to consume JSON data from our Drupal site. Let's create a new view.

• admin/structure/views/add

On the 'Add new view' form, enter values like this:

• View name: Random Word
• Show 'Content' of type 'Article' sorted by 'Unsorted'
• Check the 'Create a page' checkbox
• Path: random-word
• Display format: 'JSON data document'
• Items to display: 1
• Uncheck the 'Use a pager' checkbox

Then click the 'Continue & edit' button.

Sort Criteria

Add some 'Sort Criteria' to return a randomly selected word (article), even though we only have 1 right now. To do this, select 'Global' from the 'Filter' drop down menu, then check the box next to 'Global: Random' and then click the 'Apply (all displays)' button.

Fields

Add a Node ID field to your view. To do this, click the 'Add' button next to 'Fields', type 'nid' into the 'Search' text box, select 'Content: Nid' when it shows up in the search results list, then click the 'Apply (all displays)' button. On the next screen, change the label from 'Nid' to 'nid', then click the 'Apply (all displays)' button.

Add the translated title field to your view. To do this, click the 'Add' button next to 'Fields', type 'title' into the 'Search' text box, select 'Content: Title - Appears in node:article', then click the 'Apply (all displays)' button. On the next screen, change the label to 'title_translated', then click the 'Apply (all displays)' button.

Format (important step)

Click the 'Settings' link next to 'JSON data document' under 'Format', uncheck the 'Views API mode' checkbox and then click the 'Apply (all displays)' button.

Preview View Results in JSON

Now when we preview the results of our view, we should see something like this:

{
  "nodes" : [
    {
      "node" : {
        "title" : "Hello",
        "nid" : "1",
        "title_translated" : "Xin chào"
      }
    }
  ]
}

Save the View

Our view is ready to go, click the 'Save' button to save the view.

12. Complete the DrupalGap Hello World

Now we're ready to start building the mobile application. The easiest way to get started is to complete the Hello World for the DrupalGap mobile application development kit.

Please be patient with this step, if you've never set up a mobile application development environment, it will take some time to get started. But once you're done, you'll be ready to rock, harder than ever before.

For this example application, I installed my Drupal 7 website so it would be available here:

• http://language.tylerfrankenstein.com

Once we are up and running, and have set the 'site_path' in our settings.js file, our mobile app should look something like this:

language-dashboard.png

13. Create a Custom DrupalGap Module

Next up, we'll need a custom module in DrupalGap to build our game. We'll create a module called 'wordgame':

• www/app/modules/custom/wordgame/wordgame.js

Then we'll tell our settings.js file about the custom module:

/* Custom Modules */
Drupal.modules.custom['wordgame'] = {};

Complete details on creating a custom module for DrupalGap

14. Create a Custom Page in the Mobile App to Play the Game

Just like Drupal, we will use hook_menu() in our DrupalGap module to create a custom page.

/**
 * Implements hook_menu().
 */
function wordgame_menu() {
  try {
    var items = {};
    items['play'] = {
      title: 'Play Game',
      page_callback: 'wordgame_play'
    };
    return items;
  }
  catch (error) { drupalgap_error(error); }
}

/**
 * Page call back function for play page.
 */
function wordgame_play() {
  try {
    return 'It is time to play the game!';
  }
  catch (error) { drupalgap_error(error); }
}

Now if we set our App's front page to our newly created page, we'll see the new page. To do this, set the 'front' variable in settings.js to the 'play' page. Here is what our page will look like when our App loads:

language-game-intro.png

15. Build the Game

Our game will be pretty simple, it will grab the JSON for a random word (and its translation) from our Drupal website. Once we have the random word JSON object, we will display the translated word and provide a text field for the player to enter the English translation of the word. We'll provide buttons to let the player submit their answer, see the answer (if they don't know the answer), and to retrieve another word. Pretty basic, let's go!

var wordgame_answer = ''; // Holds the current answer.

/**
 * Implements hook_menu().
 */
function wordgame_menu() {
  var items = {};
  items['play'] = {
    title:'Play Game',
    page_callback:'wordgame_play',
    pageshow:'wordgame_play_pageshow'
  };
  return items;
}

/**
 * The page call back function for the play page.
 */
function wordgame_play() {
  var content = {
    /* Load word button */
    new_word:{
      theme:"button",
      text:"Load New Word",
      attributes:{
        onclick:"wordgame_load_new_word();"
      }
    },
    /* Word display container */
    word:{
      markup:'<div id="wordgame_word"></div>',
    },
    /* Player input form */
    player_input:{
      markup:drupalgap_get_form('wordgame_word_form')
    },
    /* Answer button */
    answer:{
      theme:'button',
      text:'View Answer',
      attributes:{
        onclick:"wordgame_view_answer();"
      }
    },
  };
  return content;
}

/**
 * The jQueryMobile pageshow call back function for the play page.
 */
function wordgame_play_pageshow() {
  wordgame_load_new_word();
}

/**
 * The player input form.
 */
function wordgame_word_form(form, form_state) {
  form.elements['translation'] = {
    type: 'textfield',
    title: 'Translation',
    required: true,
  };
  form.elements['submit'] = {
    type: 'submit',
    value: 'Check My Answer',
  };
  return form;
}

/**
 * The player input form validation handler.
 */
function wordgame_word_form_validate(form, form_state) {
  // If the translation wasn't correct, set the form error.
  if (wordgame_answer != form_state.values.translation) {
    drupalgap_form_set_error('translation', 'Sorry, that is not correct!');
  }
}

/**
 * The player input form submission handler.
 */
function wordgame_word_form_submit(form, form_state) {
  // Their answer was correct, tell them about it, then load a new word.
  drupalgap_alert('Correct!');
  wordgame_load_new_word();
}

/**
 * Loads a new word from Drupal.
 */
function wordgame_load_new_word() {
  
  // Clear previous input.
  $('#edit-wordgame-word-form-translation').val('');
  
  // Grab a random word from the Drupal site translated view JSON page:
  //   http://language.tylerfrankenstein.com/vi/random-word
  //
  //   Note: the 'vi' is the language code for Vietnamese. Replace it
  //         with the language code for the language you would like to
  //        learn.
  views_datasource_get_view_result('vi/random-word', {
      success: function(data) {
        if (data.nodes.length > 0) {
          // If there were any results, iterate over the collection.
          $.each(data.nodes, function(index, object){
              // Extract the node.
              var node = object.node;
              // Show the word to translate.
              $('div#wordgame_word').html(
                '<p>The word to translate is:</p>' + 
                '<p>' + node.title_translated + '</p>'
              );
              // Save the answer.
              wordgame_answer = node.title;
          });
        }
      }
  });
}

/**
 * Displays the current answer.
 */
function wordgame_view_answer() {
  if (wordgame_answer && wordgame_answer != '') {
    drupalgap_alert(wordgame_answer);
  }
}

Now when we run our game, it will look something like this:

language-game-controls.png

Now if we enter the word "Hello" into the text field and click the "Check My Answer" button, we have conquered the game! If we don't know the answer, we can click 'View Answer' to see the translation.

16. Add New Word

We won't get very far into learning a new language, if we can't add more words. Luckily DrupalGap has built in support for users and entities. Let's login to our Drupal site, and then create a new word (Article).

Go to the login page by, you guessed it, clicking the Login button.

language-login.png

Add a region menu link in settings.js for authenticated users that will take them to the Article node form, for example:

/* Add Word Button */
{
  'title':'Word',
  'path':'node/add/article',
  "options":{"attributes":{"data-icon":"add", "class":"ui-btn-right"}},
  "roles":{
    "value":['authenticated user'],
    "mode":"include",
  }
}

See more complete details on adding region menu links with settings.js in DrupalGap

Once we add the menu button to our settings.js file, the game will look something like this:

language-game-authenticated.png

Click the 'Add' button to go to the Article node form, add another English word, then click the 'Save' button.

language-article-add.png

17. Translate New Word

This was my first time experimenting with a multi lingual Drupal site. As the lead developer for DrupalGap, I've wanted to implement multi lingual features into DrupalGap for some time now, but haven't yet been presented the opportunity. I wanted to figure out a fun way to learn Vietnamese, and DrupalGap needs mutli lingual features, so I decided to write this demonstration game. At this point in our example game, I now see a limitation of DrupalGap. We don't yet have the feature of being able to translate nodes from within DrupalGap.

Unfortuntately for now, we'll have to translate the new word from the Admin UI back in our Drupal site. The translation of Goodbye in Vietname is, "tạm biệt". After translating the word, we should now be able to play the game with the new word.

18. Conclusion

I had fun building this little demonstration game, and hope it will keep me motivated to learn another language. I hope this example inspires you to give DrupalGap a try and see what types of fun mobile applications you can build for your Drupal site. If you'd like to contribute to DrupalGap, your code is certainly welcome. Please share your experience. Thanks for stopping by!

language-goodbye.png