Site Building (Level 1)

Set up local environment

We will start by setting up your local installation of latest stable Drupal release.

For local environment you can use various solutions: DDEV, Lando, Docksal, DrupalVM to name a few. All of those solutions are using Docker or Vagrant for setting up your environment and also have configured Drupal environments.

For the first project, we will use DDEV (https://ddev.com/, https://github.com/drud/ddev). It's an easy to use solution that uses Docker. Read documentation and quick start guides on a page and try to set up local installation with this.

Quick start for latest Drupal release: https://ddev.readthedocs.io/en/latest/users/quickstart/#drupal

A.C.

• Have a working latest Drupal website setup in a virtual environment using DDEV instructions above.

Configure Drupal by overriding default settings

There are different options as how to set and override Drupal settings so it's configured for different environments. We could use ENV variables where ENV are set on each system (Local/Dev, Staging, Production..) separately and then just parsed to Drupal in a way that Drupal only calls variable and gets the correct value from each system. Another option is to use Config split in one form or the other. We will start with basics and just address typical local settings separation that is considered a bare minimal for running the site.

By default Drupal uses settings.php to store Database and other Drupal related configuration.

More than often settings.php is one of the files that is set and committed once and then not overwritten anymore. Reason for that is, that we can configure it in a way that will support different credentials for different environments. That allows us to use one set of credentials for local environment and keep Production (live site) credentials strictly separated from the development and at the same time add additional layer of security by limiting visibility and access to production related credentials and settings.

See following site as how to set your Drupal environment in order to use local settings: https://modulesunraveled.com/drupal-8-composer-and-configuration-management/setting-settingslocalphp

NOTE: Since we are using DDEV you will notice that DDEV adds its own entry where it calls ddev.settings.php in order to overwrite Database credentials and apply few additional tweaks. That file should not be edited as any changes to it get lost on a rebuild/restart. Rather, we will write any additional settings in settings.local.php and leave ddev.settings.php as it is.

A.C.

• Edit settings.php to look for presence of settings.local.php
• Create settings.local.php .. it does not need to contain any settings for the moment.

Create and configure the Git repository

As we want to track all our changes we need to set the repository for it.

First create a new repository on Bitbucket. Second, checkout that repository locally. A new folder will be created where you can a) Copy all files from your project in it b) Copy .git folders from this folder into your project c) Use git init inside your onboard project folder and add remote urls to point towards your newly created respository.

Pick any option you prefer or try all three of them just to get the feeling and become comfortable with it.

Now that your project is wired to a repository, it's the time to commit the project to repository so we can start tracking our work.

Often it happens that there are certain files we do not want to commit as they would just be taking space and confusing anyone looking at the project or simply provide no value There is no one-size fits all but some of the common things we usually do not track (commit) are vendor folder, our environment settings (e.g. .idea file is a PHPStorm configuration that is useless to other dev's) or for example settings.local.php is also considered as non-commit-able file due nature of it.

In order to mark file not to be committed we use gitIgnore. In essence it's just a simple file that resides in a root of the project and is called ".gitIgnore". That file just contains all the paths to files or directories we do not want to be ever committed to the repository. While file itself is committed as anyone that will pull down your project will then have same rules applied - basically it wont commit any file listed in it for anyone trying to commit it.

Ensure that vendors folder and settings.local.php are on ignore list and not committed. See how to do it here: https://www.w3schools.com/git/git_ignore.asp?remote=github

Now, locally add all the files to an initial commit and push everything there. From here on, we want every task to be separately committed to the repository. If it's bigger, you can also break this to two or three commits.

For creating a good git commit message read this article and create all your commit messages based on this rules:

https://chris.beams.io/posts/git-commit

Also grant access to the repository to your assigned mentor.

A.C.

• Create the repository, sort gitIgnore and then commit your project to it and ensure your mentor can access it.
• Discuss with your mentor about the development flow that you will have to use for your on-boarding project.

Get to know Drush

Drush (DRUpal SHell) is a computer software shell-based application used to control, manipulate, and administer Drupal websites.

If you've set up your page with DDEV, Drush is already installed in the environment. You run it by prefixing it with ddev: ddev drush [command].

The most commonly used commands are 'drush cr' for rebuilding cache, 'drush cim' and 'drush cex' for importing and exporting configuration also 'drush uli' for getting a one-time login link and many many more. You can also use it to generate a scaffold of code for faster development. Run 'drush generate' to get a list of all possible generators

You can get a list of all commands by just running 'drush' (without a command) or you can check https://drushcommands.com/drush-9x/.

If you want to learn more, you can check Drush homepage: https://www.drush.org/latest/

A.C.

• Ensure Drush is working correctly by running cache-rebuild at least once.

Add first module to the project

First, we'll learn how to add a new module to the page, since you'll need an additional module in the next task already.

Recommended way of adding modules to Drupal projects is by using Composer. You can read more about this here: https://docs.acquia.com/resource/module-install-d9/

You can also add a module by using Drush (more about it also on a link above) or by manually downloading it from drupal.org, but since lots of modules need additional dependencies, you might be missing some library, so Composer is a recommended way of doing it.

First add and enable the Admin Toolbar module, which will give you an easier way of navigating through menus. To finish this task add an Address module as well and enable it. You will need it in the next task.

A.C.

Using composer

• Ensure Admin Toolbar module is installed and enabled
• Ensure Address module is installed and enabled

Content type: Company

We are using this to store information about the company.

Design: https://www.figma.com/file/lv777HRipo8xe7SJ3Z9pNr/Agiledrop-Onboarding?node-id=1979%3A1652

Fields:

1. Title*
2. Description* (text editor needed)
3. Logo*
4. Website
5. Address
6. Phone number
7. Contact email
8. Industry* (taxonomy reference, make up your own, e.g. IT, Automotive, Marketing ...)

A.C.

• Create a Taxonomy called Industry and add at least 3 different terms to it.
• Create a new content type called Company that contains all the fields listed above.

Content type: Location

We are using this to store information about location.

Design: https://www.figma.com/file/lv777HRipo8xe7SJ3Z9pNr/Agiledrop-Onboarding?node-id=1979%3A1652

Fields:

1. Title*
2. Description* (text editor needed)
3. Image*
4. Website
5. Address*
6. Phone number
7. Contact email*
8. Equipment (taxonomy reference, make up your own e.g. air-condition, parking, bar, food ...)

A.C.

• Create a Taxonomy called Equipment and add at least 3 different terms to it.
• Create a new content type for Location that contains all the fields listed above.

Content type: Event

We are using this to store information about events.

Design: https://www.figma.com/file/lv777HRipo8xe7SJ3Z9pNr/Agiledrop-Onboarding?node-id=1979%3A1652

Fields:

1. Title*
2. Description* (text editor needed)
3. Start/End date*
4. Image*
5. Event type* (taxonomy reference, make up your own e.g. sports, culture, conference ...)
6. Website (if exists, not mandatory)
7. Organizer* (reference to Company node)
8. Location* (reference to Location node)

A.C.

• Create a Taxonomy called Event and add at least 3 different terms to it.
• Create a new content type for Events that contains all the fields listed above.

Configuration export/import

Now that you already have some configuration, it's time to export the configuration of the page.

To get basic understanding of Configuration sync, check following links:

https://www.drupal.org/docs/8/configuration-management/managing-your-sites-configuration // basics https://drupalize.me/series/configuration-management https://drupalize.me/tutorial/manage-configuration-command-line-tools

After that, export the entire configuration using Drush command.

Then, you can change something on the page and try to export again, and you'll see that Drupal will recognize your changes. On the other hand, change something in exported yaml files and do configuration import, then check in drupal admin interface if change was applied.

A.C.

• Configure export location (use settings.local.php) to point towards project root (../config/sync)
• Export config using drush

Modules: Pathauto

Create path/URL aliases for all content types in format {content_type_machine_name}/{node:title}.

Example: currently your events can be accessed on /node/{nid}. After you set path aliases, events should be accessed on /event/{node:title} (ex. "/event/drupal-metup-slovenia")

A.C.

• All content types need to have aliases set in a following format: {contenttypemachinename}/{node:title}

Create content lists (Views module)

We want to display content of all three content types as lists on a separate url:

• Company list (on /companies): a list of all companies with an option to search by title or filter by industry
• Locations list (on /locations): a list of all locations with an option to search by title or filter by equipment
• Events list on /events): a list of all events with an option to search by title or filter by event type

When a user clicks on one item in a list (company, location, event), it has to go to a page with all the details.

Also add these pages to the main menu for easier access.

A.C.

• Create view pages for Company, Location and Events
• Every page should have all the content listed accordingly
• Add option to filter content by Title for each page
• All three pages should be listed as a link in a main menu for easier access/navigation

Create content blocks (Views module)

You've created a page with a list of content in a previous task. You can also use Views to create blocks which you can put in different regions.

Your job in this task is you have to create two block Views:

• Upcoming events: Create a view block which prints a list of five upcoming events from current time on sorted by the start date.
• Featured companies: Create a view block of companies that have the 'Promote to front page' checkbox set.

Hint: Views can have multiple displays and it's a good practice to combine them together, so the displays above can be under Events and Companies views from the previous task respectively.

When you're done put those two blocks in a region by your choice.

A.C.

• Create blocks for Upcoming events and Featured companies using views and logic explained above
• Show blocks on all user pages

Display: Content page

The individual page (node) should print out all fields that are on content type. Check the design files and try to print them out as they are printed there. If you are backender, you are doing this to make life easier to the frontender that will style your work. If you are frontender - well, then you are making life easier to yourself since you will have to style it afterwards.

A.C.

• Beside the fields that are on each content type, the page should have different blocks for each content type as well:
• Company: list of all events that this company is organizing with a link to each event page
• Location: list of all events organized in this location with a link to each event page
• Event: Location with brief description and link to full page, Organizer (company) with brief description and link to full page
• Print this blocks in a sidebar of individual node display.

Modules: Fieldgroup

For all three main content types, create groups of fields on edit page. Use module Fieldgroup and move fields in two or three groups (you can decide what is the name of each group and which field goes under each group). Try different types of groups: tabs, accordions, fieldset.

A.C.

• Create group of fields for all three content types
• On display of the page we want to have logo and description on company page grouped in a div with class 'company-header'.

Content type: Basic page

Create a new content type called Basic page. The point of this content type is that editors can create them with pre-defined elements, that you will create in the next ticket. Landing page will also be created using this content type.

Read more about a basic landing page: https://www.drupal.org/node/265172

A.C.

• Create new content type for Basic page

Modules: Paragraphs

In this exercise you'll be getting familiar with the Paragraphs module. You can get more information on the following links:

https://www.drupal.org/docs/contributed-modules/paragraphs https://www.webwash.net/build-edge-to-edge-sites-using-paragraphs-module-in-drupal-8/

You will have to create this paragraphs:

Slider Each slide contains a group of fields and that group can be added multiple times to format the entire slider. To do that you will have to create a new paragraph called Slide and reference it here. Slide paragraph should contain next fields:

• image*
• title
• text
• link

Text with image This paragraph should have two possible alternatives: it could have an image on the right side or image on the left side. It should contain next fields:

• image
• image alignment (can be a checkbox or a list of options - defaults to left)*
• text*

FAQ Same as with the slider paragraph, FAQ consists of a repeatable group of fields (question and answer). This paragraph therefore references a new paragraph called QA, that consist of this fields:

• Question*
• Answer*

Quote It sould consist of this fields:

• image
• quote*

Gallery It should consist of this fields:

• image (multiple images can be added)*

Using Views Reference Field module create a paragraph in which you can reference the Latest events and Featured companies view you have already created.

After all paragraphs are created, add them to content types as specified bellow:

• Basic page: slider, text with image, FAQ, gallery, quote, latest events and featured company paragraph (views reference)
• Event: gallery
• Company: quote

A.C.

• Set, configure and create aforementioned paragraphs
• Link them accordingly as stated above

Using Geofield with Geocoder

We want to display the address on Location page as a map. We can use Geofield to store and display the location, but we also need to figure what is the lat/lng of the address. For that, we can use Geocoder module (use the geocoder-php/arcgis-online-provider as a provider. To use it you will first need to require it).

After we will have this information we want to display the map on the node page. First try with Geofield directly by using Google maps, than also look at the Leaflet module and try to configure that.

A.C.

• Address on Location pages need to show up as a map.

Adjust caching for development

Things are heavily cached in Drupal. Usually you have to clear caches quite often when developing, that's why you have an option to disable most of the caches. Things might run a little slower in general, but still faster than running 'drush cr' all the time.

All the information how to prepare project for local development can be found here:

https://www.drupal.org/node/2598914

Go through the article and set you project according to the instructions. You can also explore other settings in files mentioned.

A.C.

• Disable caching on your local environment.