Difference between revisions of "Drupal/C4/Creating-a-simple-custom-module/English"

From Script | Spoken-Tutorial
Jump to: navigation, search
(Created page with " {| style="border-spacing:0;" | style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| <cent...")
 
 
Line 16: Line 16:
 
* Add a basic controller
 
* Add a basic controller
 
* add a routing file
 
* add a routing file
 
 
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| In this tutorial, we will learn to-
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| In this tutorial, we will learn to-
  
Line 23: Line 21:
 
* Add a basic '''controller''' and
 
* Add a basic '''controller''' and
 
* Add a '''routing''' file
 
* Add a '''routing''' file
 
 
  
 
|-
 
|-
Line 37: Line 33:
 
* Firefox web browser
 
* Firefox web browser
 
* Gedit text editor
 
* Gedit text editor
 
 
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| To record this tutorial, I am using
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| To record this tutorial, I am using
 
  
 
* '''Ubuntu Linux 16.04'''  
 
* '''Ubuntu Linux 16.04'''  
Line 54: Line 47:
 
* You should have basic knowledge of '''Drupal'''  
 
* You should have basic knowledge of '''Drupal'''  
 
* If not, for relevant''' Drupal''' tutorials please visit http://spoken-tutorial.org
 
* If not, for relevant''' Drupal''' tutorials please visit http://spoken-tutorial.org
 
  
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| To practise this tutorial, you should have basic knowledge of''' Drupal'''.
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| To practise this tutorial, you should have basic knowledge of''' Drupal'''.
Line 154: Line 146:
 
|-
 
|-
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Slide 5: Module Naming Conventions
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Slide 5: Module Naming Conventions
 
  
 
* It must contain only lower-case letters, underscores and no spaces  
 
* It must contain only lower-case letters, underscores and no spaces  
 
* It must be unique and can not have the same short name
 
* It must be unique and can not have the same short name
 
* It should not be any reserved terms such as '''src, lib, vendor, templates, includes, fixtures'''
 
* It should not be any reserved terms such as '''src, lib, vendor, templates, includes, fixtures'''
 
 
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| There are some rules to follow when naming a '''custom module'''.
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| There are some rules to follow when naming a '''custom module'''.
 
  
 
* It must contain only lower-case letters, underscores but no spaces.  
 
* It must contain only lower-case letters, underscores but no spaces.  
Line 185: Line 173:
 
|-
 
|-
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Slide 6: YAML
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Slide 6: YAML
 
  
 
* '''Yml''' is the file extension of '''YAML'''
 
* '''Yml''' is the file extension of '''YAML'''
 
* YAML is a unicode based data serialization standard for all programming languages
 
* YAML is a unicode based data serialization standard for all programming languages
 
* It is a human-readable language.
 
* It is a human-readable language.
 
 
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| '''Yml''' is the file extension of '''YAML'''.
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| '''Yml''' is the file extension of '''YAML'''.
  
Line 199: Line 184:
  
 
It is a human-readable language.
 
It is a human-readable language.
 
 
 
  
 
|-
 
|-
Line 229: Line 211:
 
|-
 
|-
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Highlight name
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Highlight name
 
 
 
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| This is the title of our '''module''' shown on the '''extend''' page.
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| This is the title of our '''module''' shown on the '''extend''' page.
  
Line 325: Line 304:
 
|-
 
|-
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Point to '''Hello World '''under '''Custom'''
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Point to '''Hello World '''under '''Custom'''
 
 
 
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Under '''Custom''', you can see the '''Hello World module '''which we created just now.
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Under '''Custom''', you can see the '''Hello World module '''which we created just now.
  
Line 346: Line 322:
 
|-
 
|-
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| '''Slide 7: Router'''
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| '''Slide 7: Router'''
 
  
 
* This is to tell Drupal where the module can be accessed from.  
 
* This is to tell Drupal where the module can be accessed from.  
 
* The router determines what should be done with the request.
 
* The router determines what should be done with the request.
 
* The router also checks if the access is permitted.
 
* The router also checks if the access is permitted.
 
 
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Next, we have to add the''' router file'''.  
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Next, we have to add the''' router file'''.  
  
Line 432: Line 405:
 
* '''Controller''' is a PHP function
 
* '''Controller''' is a PHP function
 
* It takes information from the HTTP request and constructs and returns an HTTP response
 
* It takes information from the HTTP request and constructs and returns an HTTP response
 
 
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| What is a '''controller'''?
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| What is a '''controller'''?
  
Line 484: Line 455:
 
}
 
}
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Inside this file, type the following.
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Inside this file, type the following.
 
 
 
  
 
|-
 
|-
Line 566: Line 534:
 
* Add a basic controller
 
* Add a basic controller
 
* Add a route file
 
* Add a route file
 
 
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Let us summarize.
 
| style="background-color:#ffffff;border:1pt solid #000001;padding-top:0cm;padding-bottom:0cm;padding-left:0.079cm;padding-right:0.191cm;"| Let us summarize.
  
Line 576: Line 542:
 
* Add a basic '''controller'''
 
* Add a basic '''controller'''
 
* Add a '''routing''' file
 
* Add a '''routing''' file
 
 
  
 
|-
 
|-

Latest revision as of 13:06, 22 May 2018

Visual cue
Narration
Slide 1:

Creating a simple custom module

Welcome to the spoken tutorial on Creating a simple custom module.
Slide 2: Learning Objectives
  • Create a basic module
  • Add a basic controller
  • add a routing file
In this tutorial, we will learn to-
  • Create a basic module
  • Add a basic controller and
  • Add a routing file
Slide 3:

System requirement

To record this tutorial, I am using

  • Ubuntu Linux 16.04 OS
  • Drupal 8
  • Firefox web browser
  • Gedit text editor
To record this tutorial, I am using
  • Ubuntu Linux 16.04
  • Drupal 8
  • Firefox web browser and
  • Gedit text editor

You can use any text editor and web browser of your choice.

Slide 4a: Pre-requisites To practise this tutorial, you should have basic knowledge of Drupal.


If not, for relevant Drupal tutorials, please visit the link shown.

Slide 4b: Pre-requisites
  • Object oriented programming terminology
  • Programming in PHP
  • Namespacing in PHP
  • Symfony 2

For more details, please see the “Additional reading material” link

To create a custom module in Drupal, you should be familiar with
  • Object oriented programming terminology
  • Programming in PHP
  • Namespacing in PHP and
  • Symfony 2

For details of pre-requisites, please see the “Additional reading material” link of this tutorial.

We have already learnt about contributed modules earlier.


Now we will learn to create a simple custom module.

show the page This module will create a custom page showing “hello world”.
image Here is the workflow of this module.


The Request is what we request to the website.


Router determines what should be done with the request.


The controller builds the response for the given request.


The View creates the response.


The response is what the website returns.

Here is the file structure of the custom module which we are going to create.
Open the File browser Let us start creating the files required for a custom module.


Open your File browser.

Go to drupal-8.4.4-0 Go to the folder where we have installed Drupal locally.
Go to apps -> drupal -> htdocs -> modules


Point to modules folder

Now go to apps -> drupal -> htdocs -> modules folder.


We have to always create our custom modules inside this modules folder.

Create a folder custom Let’s create a folder and name it as custom.


This will separate our custom modules from the contributed modules.

Create a folder hello_world Inside this custom folder, we will create a folder called hello_world.
This folder name is the machine name.


It will be used by core Drupal programmatically, to refer to this module.

Slide 5: Module Naming Conventions
  • It must contain only lower-case letters, underscores and no spaces
  • It must be unique and can not have the same short name
  • It should not be any reserved terms such as src, lib, vendor, templates, includes, fixtures
There are some rules to follow when naming a custom module.
  • It must contain only lower-case letters, underscores but no spaces.
  • It must be unique and cannot have the same short name as any other module or theme
  • It cannot have any reserved terms such as src, lib, vendor, templates, includes, fixtures, etc.

<<PAUSE>>

Create hello_world.info.yml file in gedit


Highlight the folder name and file name

We are inside this hello_world folder.


Here, we will create a file called hello_world with info.yml extension.


The name of the info.yml file and the name of the module folder should be the same.

Slide 6: YAML
  • Yml is the file extension of YAML
  • YAML is a unicode based data serialization standard for all programming languages
  • It is a human-readable language.
Yml is the file extension of YAML.


YAML is a unicode based data serialization standard for all programming languages.


It is a human-readable language.

Copy and paste it

name: Hello World

description: A page displaying "Hello World"

package: Custom

type: module

core: 8.x

This info.yml file is to tell Drupal about our module.


In this file, we will store the metadata of our module.


So type the following metadata.

Press ctrl+s to save And save the file.
Highlight name This is the title of our module shown on the extend page.
Highlight description This is a small description of our module.
Highlight package This is what category our module will be listed under on the extend page.
Highlight type This is to tell Drupal that we are making a module.
Highlight core The core key specifies the version of Drupal core that our module is compatible with.
Highlight name, type, core Here name, type and core keys are required. Other keys can be ignored.


<<PAUSE>>

Create hello_world.module in gedit Next, we will create a file called hello_world with module extension.
Copy and paste it

<?php

/**

* @file

* Hello World module.

*/

For this demonstration, we are not going to add any functionality in this file.


But we just need to create this file.


In this file, type the following.

Press ctrl+s to save Let us save the file.
Point to hello_world.info.yml and hello_world.module These are the two files Drupal requires to create a module.


<<PAUSE>>

Open drupal website Now we will install this module in our website.


Open our local Drupal website.

Click Configuration menu Before installing the new module, we will clear the cache first.

To do that, click on the Configuration menu.

Click Development -> Performance Under Development, click on the Performance option.
Click Clear all caches Now click on the Clear all caches button.


You can see that the caches are cleared.


It is compulsory to clear the caches every time we modify our website.

Click Extend menu and scroll down Now to install the module, click on the Extend menu and scroll down.
Point to Hello World under Custom Under Custom, you can see the Hello World module which we created just now.
Click on it Click on it to select.
Click Install button Click on the Install button at the bottom.


Our custom module is enabled now.


<<PAUSE>>

Slide 7: Router
  • This is to tell Drupal where the module can be accessed from.
  • The router determines what should be done with the request.
  • The router also checks if the access is permitted.
Next, we have to add the router file.


This is to tell Drupal where the module can be accessed from.


The router determines what should be done with the request.


The router also checks if the access is permitted.

Switch File browser For that, switch back to our File browser.
Create hello_world.routing.yml in gedit Now we will create the routing file called hello_world.routing.yml
Copy and paste it

hello_world.content:

path: '/hello'

defaults:

_controller: '\Drupal\hello_world\Controller\HelloWorldController::content'

requirements:

_permission: 'access content'

Type the following inside the routing file.


Let us understand the code.

Highlight hello_world.content


Highlight path: '/hello'


Highlight _controller: '\Drupal\hello_world\Controller\HelloController::content'


Highlight _permission: 'access content'

This line is the route.


This indicates what path will be used to access our module.


This is to tell Drupal where to get the content from.


Here content is the function which we will create in the controller file.


This is to ensure only users who can access content, will be able to see our Hello World page.


<<PAUSE>>

Next we should add the functionality about what this module is going to do.


This is done by adding a controller.

Slide 8: Controller


  • Controller is a PHP function
  • It takes information from the HTTP request and constructs and returns an HTTP response
What is a controller?


Controller is a PHP function.


It takes information from the HTTP request and constructs and returns an HTTP response.

Switch to File browser Switch back to our File browser.
Create src folder To add a controller, we should create a folder named src here.
Create Controller folder Inside the src folder, we should create another folder named Controller.
Create HelloController.php file Inside this Controller folder, we will create the controller file called HelloController.php
<?php


namespace Drupal\hello_world\Controller;


use Drupal\Core\Controller\ControllerBase;


class HelloWorldController extends ControllerBase {

public function content() {

return array (

'#title' => 'Hello World',

'#markup' => 'Welcome to the Drupal Development World!'),

);

}

}

Inside this file, type the following.
Press ctrl+s to save Now save the file.
Highlight

namespace Drupal\hello_world\Controller;


Highlight use Drupal\Core\Controller\ControllerBase;


Highlight class HelloWorldController

'#title' => 'Hello World',

'#markup' => 'Welcome to the Drupal Development World!'),

The namespace allows to place a bunch of code under a name, to avoid naming conflicts.


This use statement will import the ControllerBase class.


We have a class HelloWorldController with the function content.


It will return the markup text when the routing system invokes the page.


<<PAUSE>>

Switch to web browser. Now switch to the web browser.
Click Back to site button Click on the Back to site button.
In address bar, type hello


Highlight /hello in the routing.yml file

Add hello in the address bar as a request to the web browser.


This is the path we created in the routing file to access our module.


Now press Enter.


We can see our custom page which we created just now. This is the response.

Likewise, we can create other simple custom modules in Drupal 8.
With this, we come to the end of this tutorial.


<<PAUSE>>

Slide 9:

Summary

In this tutorial, we have learnt to-

  • Create a basic module
  • Add a basic controller
  • Add a route file
Let us summarize.


In this tutorial, we have learnt to-

  • Create a basic module
  • Add a basic controller
  • Add a routing file
Slide 10:

Assignment


Create a custom module for “About us” page of your website

As an assignment, create a custom module for “About us” page of your website.
Slide 11:

Acknowledgement


The video at the following link summarises the Spoken Tutorial project.


Please download and watch it.

Slide 12:

Spoken Tutorial Workshops


The Spoken Tutorial Project Team conducts workshops and gives certificates.


For more details, please write to us.

Slide 13:

Acknowledgement


Spoken Tutorial Project is funded by
  • NMEICT, Ministry of Human Resource Development and
  • NVLI, Ministry of Culture

Government of India.

This is Priya from IIT Bombay signing off. Thanks for joining.

Contributors and Content Editors

Nancyvarkey, Priyacst