-
Joe 🤘 Shindelar authoredJoe 🤘 Shindelar authored
Drupal User Guide
- 1. Preface
- 2. Understanding Drupal
- 3. Planning Your Site
- 4. Installation
- 5. Basic Site Configuration
- 6. Basic Page Management
- 7. Setting Up Content Structure
- 8. Managing User Accounts
- 9. Blocks
- 10. Creating Listings with Views
- 11. Making Your Site Multilingual
- 12. Extending and Customizing Your Site
- 13. Preventing and Fixing Problems
- 14. Security and Maintenance
- 15. Final Thoughts
- 16. Index
- Appendix A: Appendix
1. Preface
Overview of introductory topics that help to leverage this guide in an efficient manner.
1.1. Copyright
Copyright information for this guide.
This guide was written by contributors to the Drupal open-source project. It is copyright 2015-copyright_upper_year by the individual contributors, and can be used in accordance with the Creative Commons License, Attribution-ShareAlike 2.0 (CC BY-SA 2.0). Each page in this document (including this one) has an Attributions statement at the bottom, listing the people who contributed to writing and editing that page. See also [attributions] for guide-wide editing, translating, and project management information.
The CC BY-SA license (very similar to the GPL) allows anyone to copy, modify, and redistribute modifications of all or part of this work, as long as the following is complied with:
-
You provide appropriate credit (see the license for more information).
-
You provide a link to the license.
-
You indicate whether changes have been made.
-
You distribute your work under the same license as this original.
Attributions
This page was adapted and edited by Jennifer Hodgdon, and Jojy Alphonso at Red Crackle, from "Documentation copyright and licensing", copyright 2000-copyright_upper_year by the individual contributors to the Drupal Community Documentation.
Copyright notice: Copyright 2015-copyright_upper_year by the individual contributors; see Copyright for details. Licensed under CC BY-SA 2.0.
1.2. Audience and Goal
Understanding the target audience for this guide, and what they will learn from it.
This guide was written mainly for people with minimal knowledge of the Drupal content management system. The topics will help them become skilled at installing, administering, site building, and/or maintaining the content of a Drupal-based website. The guide is also aimed at people who already have some experience with a current or past version of Drupal, and want to expand the range of their skills and knowledge or update them to the current version.
This guide assumes that you have already decided you want to learn and use Drupal. If you need to learn more before deciding, see Concept: Drupal as a Content Management System.
Depending on which aspects of Drupal you would like to learn, you will need some background knowledge to understand this guide: general Internet skills and knowledge are assumed, and the guide concentrates on how to use the software itself. For instance, the sections about installing Drupal on a web server assume you can obtain web hosting and figure out how to transfer files to your chosen web host. Similarly, the sections about content management assume you can log into a website and fill in a web-based form.
After reading this guide, you should be able to:
-
Plan the content architecture for a Drupal-based site
-
Build the site that you planned
-
Manage and administer your site
-
Understand documentation and blog posts on topics not covered here, to expand your knowledge and skills
-
Connect with the worldwide Drupal community
Attributions
Written by Jennifer Hodgdon.
1.3. Organization
Understanding the organizational structure of this guide for better navigation through topics.
This user guide contains a series of topics, each of which covers either a task (how to do something) or a concept (background knowledge, terminology, and the like). Concept topics have names starting with Concept:, while task topics have names containing verbs, like Editing Basic Site Information.
The topics are grouped into chapters in a logical order, with concepts and tasks interleaved so that concepts are presented before related tasks, and tasks build on each other. To take advantage of this, you are encouraged to read the entire guide in its presented order, possibly skipping topics that are not of interest or that present information you already know. Remember to try out the tasks on your own site as you read the guide; most people learn better by doing rather than reading.
If you prefer, you can also use the index or table of contents to jump straight to a topic that you’d like to learn about, rather than reading the entire guide. To facilitate this approach, each topic lists the prerequisite knowledge that you’d need in order to understand it, if any (with links to the topics that present that knowledge); task topics also list site prerequisites (things that you would need to have configured or created on your site in order to perform the task). Also, most topics have sections at the end where you can find related information and/or tasks for expanded understanding, to continue your learning.
You may also want to refer to the [glossary] section as you read — it gives brief definitions of most of the terminology used in the guide, with links to topics having more detailed explanations.
Attributions
Written by Jennifer Hodgdon.
1.4. Reporting Problems
How to report an issue with this guide (with detailed steps).
Goal
Report a problem with this guide, such as:
-
Information that is incorrect or does not follow best practices
-
Steps that do not work
-
Screenshots or text that doesn’t match what you see on the screen
-
Unclear writing
-
Places where a table or screenshot would help clarify the text
-
Failure to define terminology
-
Missing knowledge prerequisites or site prerequisites for a topic
-
Typographical, spelling, grammar, or formatting errors
-
Broken links
Steps
-
Make a note of the topic or topics that contain the problem you have found.
-
Log in to Drupal.org (you will need to create a user account if you do not already have one).
-
Visit the User Guide issues page on Drupal.org.
-
Verify that the problem you found has not already been reported in another issue:
-
If there are only a few open issues, scan the Summary column to see if any of their descriptions match the problem you found. You may also need to read some of the issues to make sure, which you can do by clicking the links in the Summary column.
-
If the open issue list is long, enter either a keyword related to the problem you found or the title of the topic where the problem occurs in the Search for box, and click Search to reduce the issue list. Then either scan the summaries or read the issues to see if they match your problem.
-
-
If you determine that your problem has not already been reported, click Create a new issue, and fill in the issue report as follows:
Field name Explanation Example value Title
Short summary of the problem you found
Instructions in "Adding a Content Type" do not work
Category
Type of issue being reported
Bug report
Version
Version of the guide you found the problem in
9.1.x-dev
Issue summary
Details of the problem you found
In the "Adding a Content Type" topic, in step 3, when I clicked Save, I got the following error message: …
-
Reread the Title and Issue summary you entered, and verify that the following information is included in your report:
-
A complete description of the problem you found
-
The name of the topic or topics where you found the problem
-
The language you are reading the guide in (if not English)
-
If you read the guide on a website, a link to the page or pages with the problem
-
-
Click Save to create the issue.
-
Check back on the issue in a few days. If one of the project maintainers has asked for clarification, respond by adding a comment to the issue.
Attributions
Written by Jennifer Hodgdon.
1.5. Conventions of the Guide
Understanding the conventions used in this guide.
Assumptions and prerequisites
This guide has the following assumptions and prerequisites:
-
This guide covers the current major version of the core software.
-
This guide is organized into topics; see Organization for details. Many topics include a Prerequisite knowledge section, which lists other topics whose content knowledge is needed in order to understand the topic you are reading. Some background knowledge that is not covered in the guide is also assumed; see Audience and Goal for details.
-
Many task topics list Site prerequisites, which are tasks that you’ll need to have completed on your site before you’ll be able to do the task in the topic you are reading.
-
The specifics of the site prerequisites relate to the scenario used throughout this guide of building a site for a farmers market (see Guiding Scenario for details). You can adapt the tasks to your own scenario, but you will also need to remember the changes you made when deciding if your site satisfies the site prerequisites for a task.
-
For all task topics after Running the Interactive Installer, there is also an implicit prerequisite: you must have installed the latest stable version of the content management software on your site, and be logged in to a user account with sufficient permissions to do the task (such as the user account created when you installed your site, which automatically has full permissions).
-
If you read all the topics in order, and perform all of the steps in the task topics as you go (staying logged in), you should have the background knowledge and site prerequisites in place for each topic as you read it.
-
This guide demonstrates how to perform tasks using the administrative user interface, and wherever possible, also using the latest stable version of the Drush command-line tool (see Concept: Additional Tools). You can feel free to only use the administrative interface depending on your preference.
Text conventions
The following conventions are used in the text of this guide:
-
The URL example.com means the base URL of your website. See the Navigation section below for more details on how URLs internal to your site are indicated.
-
Text you should see in the user interface of your site is shown in italics, such as: Click Save configuration. This only applies to text in the user interface that comes from the software, not to text that was entered in a previous topic. For example, in a topic about editing, you might see this instruction: Click Edit in the row of the About page (Edit would be in italics, but About would not be, because the About page was created in a previous topic).
-
URLs, file names, and newly-introduced terminology are also shown in italics.
-
Text that you should type at a shell command line is shown in monospace type, such as:
drush cache:rebuild
-
Within this guide, the word directory is always used to refer to file directories (which some people prefer to call folders).
Navigation
To do most of the task topics in this guide, you will need to navigate to one or more pages in the administrative interface of your site. You might see something like this in the instructions (this will make more sense after you have the base software installed):
In the Manage administrative menu, navigate to Structure > Taxonomy (admin/structure/taxonomy).
Navigation instructions like this assume that you have the core Toolbar module installed, and this example means that in the menu bar at the top of your site, you would need to click Manage to expose the menu choices, then click Structure, then Taxonomy, and that at the end, you would be on a page with URL http://example.com/admin/structure/taxonomy (if your site base URL is http://example.com).
Here’s another example:
In the Manage administrative menu, navigate to Configuration > System > Basic site settings (admin/config/system/site-information).
In this example, after clicking on Manage and Configuration, you would need to find the System section of the page, and within that, click Basic site settings. After that, you’d end up on http://example.com/admin/config/system/site-information.
One other note: if you are using the standard administrative core Seven theme, many "Add" buttons in the administrative interface are displayed with + signs on them. For instance, on admin/content, the Add new content button appears as + Add new content. However, this is theme-dependent and is not really part of the text on the button (for instance, it would not necessarily be read by a screen reader), so in this guide, the convention is to not mention the + sign on the buttons.
Filling in forms
Many of the task topics in this guide include steps where you will fill out a web form. In most cases, a screen capture image of the form will be included, along with a table of the values you will need to enter into each form field. For example, you might see a table that starts out like this, explaining the site information form you would see if you navigated to Configuration > System > Site information (admin/config/system/site-information):
| Field name | Explanation | Example value |
|---|---|---|
Site details > Site name |
Name of your site |
Anytown Farmers Market |
To use this table, find the field labeled Site name in the section that is under Site details in the form, and enter the name of your site in this field. An example site name of "Anytown Farmers Market" is suggested in the table, which relates to the scenario of building a website for a farmers market that you’ll find all through this guide (see Guiding Scenario for details). Also note that on some forms, you might have to click a section title (like Site details in this example) to expand the section and find the field it contains.
Attributions
Written/edited by Jennifer Hodgdon.
1.6. Guiding Scenario
Understanding the project scenario used in this guide to follow the topics better.
When reading this guide, it is helpful to have a website building project in mind. The following project scenario provides context and links together the examples in this guide:
You are making a website for a farmers market. The site needs to display information about the location and hours of the market, and an About page with the history of the market. It also needs to list the vendors. Vendors should be able to edit their listings (including a logo or photo), and post recipes. Site visitors should be able to browse recipes, or locate recipes using ingredients that they purchased at the market. Some visitors to your site speak another language, so the main pages and vendor pages need to be translated.
As you read through the guide and try out the tasks it describes, you may choose to follow the scenario exactly; you could also modify the tasks to suit your purposes. If you do want to follow the scenario exactly, you’ll find that you need some image files, which are located in the assets directory of the .zip or .tgz file download available on the User Guide project page.
Attributions
Written/edited by Jennifer Hodgdon.
2. Understanding Drupal
Overview of Drupal concepts such as modules, themes, distributions, and types of data.
2.1. Concept: Drupal as a Content Management System
Overview of Drupal and the reasons to choose it as a reliable Content Management System (CMS).
What is a Content Management System?
A content management system (CMS) is a software tool that lets users add, publish, edit, or remove content from a website, using a web browser on a smartphone, tablet, or desktop computer. Typically, the CMS software is written in a scripting language, and its scripts run on a computer where a database and a web server are installed. The content and settings for the website are usually stored in a database, and for each page request that comes to the web server, the scripts combine information from the database and assets (JavaScript files, CSS files, image files, etc. that are part of the CMS or have been uploaded) to build the pages of the website.
The combination of the operating system that the CMS runs on, the scripting language it is written in, the database it stores its information in, and the web server that runs the scripts to retrieve information and return it to the site visitor’s web browser is known as the stack that the CMS runs on; the commonly used combination of the Linux operating system, Apache web server, MySQL database, and PHP scripting language is known as the LAMP stack.
What is Drupal?
Drupal is a flexible CMS based on the LAMP stack, with a modular design allowing features to be added and removed by installing and uninstalling modules, and allowing the entire look and feel of the website to be changed by installing and uninstalling themes. The base Drupal download, known as Drupal Core, contains the PHP scripts needed to run the basic CMS functionality, several optional modules and themes, and many JavaScript, CSS, and image assets. Many additional modules and themes can be downloaded from the Drupal.org website.
Drupal can also run on other technology stacks:
-
The operating system can be Windows or Mac OS instead of Linux.
-
The web server can be Nginx or IIS instead of Apache.
-
The database can be PostgreSQL or SQLite instead of MySQL, or a MySQL-compatible replacement such as MariaDB or Percona.
Other operating systems, web servers, and databases can also be made to work; however, the scripts that the software uses are written in PHP, so that cannot be changed.
What are the reasons for using Drupal?
When building a website, you have your choice of using one of the many existing CMS packages and hosted services, developing your own CMS, or building the site without using a CMS. Here are some of the reasons you might choose to use Drupal:
-
Building a small, simple site with static HTML pages is not difficult, and you can get a simple site up very quickly. Setting up a site in a CMS generally requires more time initially, but brings you the benefits of on-line editing (easier for less experienced content maintainers), uniformity (harder to maintain using static HTML for larger sites), and the possibility of more complex features requiring a database.
-
Some CMS software is special-purpose; for instance, there are packages and hosted services that you can use to build a blog or a club membership website. Drupal, in contrast, is a general-purpose CMS. If you are building a special-purpose site, you might choose to use a special-purpose CMS; however, if your site falls even slightly outside the intended purpose, you will probably be better off using a general-purpose CMS rather than trying to adapt a special-purpose CMS.
-
Building your own CMS-type software can seem attractive. However, using a general-purpose CMS like Drupal as a starting point is usually a better idea, because the basic CMS functionality (such as user accounts and content management) has thousands of developer hours behind it, including many years of user testing, bug fixing, and security hardening.
-
Some CMS software packages are expensive to purchase a license for. Some are free or have a free version, but have restrictive licenses that do not allow you to make modifications and extensions. You might prefer to use a package (like Drupal) that has a less restrictive software license, and is developed by a world-wide community. See Concept: The Drupal Project for more on this topic.
Additional resources
Attributions
Written and edited by Kristof van Tomme at Pronovix, Jennifer Hodgdon, and Michael Lenahan at erdfisch.
2.2. Concept: Modules
Overview of modules and the functionality they can be used for.
What is a module?
A module is a set of PHP, JavaScript, and/or CSS files that extends site features and adds functionality.
You can turn the features and functionality on by installing the module, and you can turn it off by uninstalling the module; before uninstalling, you may need to remove data and configuration related to the feature or functionality.
Each module that is installed adds to the time needed to generate pages on your site, so it is a good idea to uninstall modules that are not needed.
The core download provides modules for functionality such as:
-
Managing user accounts (the core User module)
-
Managing basic content (the core Node module) and fields (the core Field and Field UI modules; there are also core modules providing field types)
-
Managing navigation menus (the core Menu UI module)
-
Making lists, grids, and blocks from existing content (the core Views and Views UI modules)
You can download additional contributed modules from the Drupal.org Module Downloads, or create your own custom modules.
2.3. Concept: Themes
Overview of themes and where to obtain them.
What is a Theme?
A theme is a set of files that define the visual look and feel of your site. The core software and modules that run on your site determine which content (including HTML text and other data stored in the database, uploaded images, and any other asset files) is displayed on the pages of your site. The theme determines the HTML markup and CSS styling that wraps the content.
The core software provides several basic themes with the core distribution. These themes have largely been designed and built by the community over the last several years and will all be good choices for building your first sites and becoming more familiar with how the core software works.
Drupal is a well-established CMS so the market for 3rd party themes - both free and paid - is very robust.
If none of the 3rd party options suit your needs, you’ll need to create a custom theme. A custom theme can be as simple as a single CSS file that adds styling to the markup provided by the core software. Guidance for creating custom themes in Drupal can be found in the Drupal.org community documentation page "Theming Drupal".
2.4. Concept: Distributions
Overview of distributions, which can be used to set up websites for specific purposes.
What are Distributions?
Distributions provide site features and functions for a specific type of site as a single download containing the core software, contributed modules, themes, and pre-defined configuration. A distribution makes it possible to set up a complex site for a specific purpose, in fewer steps than installing and configuring elements individually.
There are two main types of distributions:
- Full-featured Distributions
-
A full-featured distribution is a project that provides a complete solution to set up a site for a specialized purpose, such as academic, business, government, nonprofit, publishing, social, etc. For example, you could use an existing distribution for farmers markets to build your own website, or you could share your set-up for the farmers market site as a distribution for others to use.
- Other Distributions
-
Distributions can also be quick-start tools that developers and site builders can use as a starting point.
Additional resources
Attributions
Adapted and edited by Diána Lakatos and Antje Lorch, from "Distributions" and "Download & Extend — Distributions" copyright 2000-copyright_upper_year by the individual contributors to the Drupal Community Documentation.
2.5. Concept: Types of Data
Overview of common types of data used in a site.
What are the types of data?
The data and information on your site is divided up into four types, which are edited, translated, and stored differently. These four types are:
- Content
-
Information (text, images, etc.) meant to be displayed to site visitors. This type of information tends to be relatively permanent, but can normally be edited.
- Configuration
-
Information about your site that is not content, but is also relatively permanent, and is used to define how your site behaves or is displayed. It is sometimes also displayed to site visitors, but tends to be smaller pieces of text (like field labels, the name of your site, etc.) rather than larger chunks that you’d normally think of as Content.
- State
-
Information of a temporary nature about the current state of your site, such as the time when cron jobs were last run.
- Session
-
Information about individual site visitors' interactions with the site, such as whether they are logged in and their cookies. This is technically a subtype of State information, since it is also temporary.
Related topics
Attributions
Adapted by Jennifer Hodgdon from "Overview of Configuration (vs. other types of information)", copyright 2000-copyright_upper_year by the individual contributors to the Drupal Community Documentation
2.6. Concept: The Drupal Project
Overview of Free and Open Source Software (FOSS), Drupal project, and Drupal Association.
What is Free and Open Source Software?
Free and Open Source Software (FOSS) is software that is developed by a community of people, released under a non-commercial license, and whose source code (the program files that make up the software) is freely available. For more information on the non-commercial license used by Drupal, see Concept: Drupal Licensing.
What is the Drupal project?
The Drupal project is a FOSS project whose purpose is to develop the core content management system software, as well as add-on modules, additional themes, translations, documentation, and special-purpose distributions. The people who contribute their time and money to the Drupal project come from all over the world, and are a diverse community that comes together for this common purpose.
The community encompasses many smaller groups who perform many different tasks such as developing a particular piece of Drupal-related software, writing documentation, maintaining the security of Drupal software, translating Drupal software into a particular language, using Drupal for some specific purpose, and coming together to meet in person within a particular geographical area.
For more on how you can connect to and communicate with the world-wide community, see [thoughts-connecting] and [thoughts-support].
What is the Drupal Association?
The Drupal Association is a non-profit organization dedicated to supporting the Drupal project and community. Its main functions are:
-
Putting on large conventions around the world
-
Maintaining the Drupal.org websites and the servers that they run on
-
Promoting Drupal as a web platform
-
Supporting Drupal education and training
-
Providing grants to the Drupal community in support of its mission
-
Raising funds for these purposes
2.7. Concept: Drupal Licensing
Overview of Drupal licensing and the guidelines to be followed by users and contributors.
What is Drupal Licensing?
Drupal and all contributed files hosted on Drupal.org are licensed under the GNU General Public License (GPL), version 2 or later. That means you are free to download, reuse, modify, and distribute any files that are part of a project on Drupal.org under the terms of GPL version 2 or 3. You can also run the core software in combination with any code with any license that is compatible with version 2 or 3.
Drupal contributors should follow these guidelines:
-
All files (PHP, JavaScript, images, Flash, etc.) that are part of a project on Drupal.org have to be under GPL version 2 or later.
-
All Drupal contributors retain copyright on their code, but agree to release it under the same license as Drupal.
-
Drupal modules and themes are a derivative work of Drupal. If you distribute them, you must do so under the terms of GPL version 2 or later.
-
All content on Drupal.org itself is copyrighted by its original contributors, and is licensed under the Creative Commons Attribution-ShareAlike license 2.0.
-
Sample code on Drupal.org is also available under GPL version 2 or later.
Additional resources
Attributions
Adapted by Diána Lakatos at Pronovix from "Licensing" copyright 2000-copyright_upper_year by the individual contributors to the Drupal Community Documentation.
3. Planning Your Site
Overview of site planning concepts and details of common site layout tasks. Content entity and structure concepts are covered.
3.1. Concept: Regions in a Theme
Overview of regions from a theming perspective.
What is a region?
Besides its primary content, a web page contains other content such as site branding (site name, slogan, and logo), navigation aids (menus, links, and icons), formatted text, and images. Each theme provides a set of named regions, such as Header, Content, and Sidebar, where site builders may choose to place their content.
The available regions depend on the theme design. Only the Content region, which contains the primary content, is required; others are optional. The core Olivero theme provides the regions highlighted in the following image.
Related topics
Attributions
Written and edited by John MacDonald, Michael Lenahan at erdfisch, and Joe Shindelar at Drupalize.Me.
3.2. Planning Your Site Layout
How to plan the navigation and layout of a website (mobile and desktop browsers).
Steps
It is a good idea to plan the site layout before you start building the site and writing content; however, your plan may need to be revised either before you start implementing it or after you have some of the site built with draft content in place, based on budgetary concerns or stakeholder feedback.
-
Make a list of the information that your site should present to visitors. In the farmers market scenario, this might include:
-
Location of the market, with directions and a map
-
Hours and days the market is open
-
History of the market
-
List of vendors
-
Details about each vendor
-
Searchable list of recipes
-
Details about each recipe
-
List of the most recently added recipes
-
-
Decide which information should be on which pages or types of pages on the site:
- Information that should be on all pages
-
Address, hours, and recently-added recipes list
- Vendor details pages
-
Information about each vendor on its own page
- Recipe details pages
-
Details of each recipe on its own page
- Home page
-
Location, map, directions, and hours
- About page
-
History of the market
- Vendors list page
-
List of vendors, with links to vendor detail pages
- Recipe list page
-
Searchable list of recipes, with links to recipe detail pages
-
Decide which information is the most important on each page. Site visitors using mobile phones or other small browsers will often only see the content that is presented first, and they may not scroll down to see all of the information.
-
Decide which of these pages should appear in the main site navigation. For instance, the main navigation might consist of the Home, About, Vendors, and Recipes pages.
-
Make a rough design sketch for each page, showing how it would look when viewed on a small screen such as a phone, as well as on a larger screen such as a desktop browser. Considering that most site visitors will be using smaller browsers, it is a good idea to start with the phone-size layout, to make sure that these visitors will be able to find the information they need without too much scrolling.
In making these page layout plans, you might find that you need to revise your plan for which information should be on which pages. For example, you might decide that the address, hours, and recently-added recipes list would all fit well in the right sidebar area of all pages, when the site is viewed on desktop-sized browsers. On the other hand, you might decide that for mobile browsers, you would instead put the address and hours in a short format at the top of each page, but only display the recent recipe list at the bottom of the home page.
Videos
Attributions
Written by Jennifer Hodgdon.
3.3. Concept: Content Entities and Fields
Overview of content entities and fields.
What is a content entity?
A content entity (or more commonly, entity) is an item of content data, which can consist of text, HTML markup, images, attached files, and other data that is intended to be displayed to site visitors. Content entities can be defined by the core software or by modules.
Content entities are grouped into entity types, which have different purposes and are displayed in very different ways on the site. Most entity types are also divided into entity subtypes, which are divisions within an entity type to allow for smaller variations in how the entities are used and displayed. Here is a table of some common content entity types:
| Entity type | Entity subtype | Defining Module | Main uses |
|---|---|---|---|
Content item |
Content type |
Node module |
Content intended to be the main page area for pages on the site |
Example: In the farmers market site example, you might have content types for basic pages, vendor pages, and recipe pages. |
|||
Comment |
Comment type |
Comment module |
Commentary added to content entities (typically to Content item entities) |
Example: On a blog site, blog posts might have comments. They are not needed in the farmers market site example. |
|||
User profile |
(none) |
User module |
Data related to a person with a user account (login access) on the site |
Example: Every site has at least basic user profiles with user names and email addresses; social networking sites may have more complex user profiles with more information. |
|||
Custom block |
Block type |
Custom Block module |
Text and images in smaller chunks, often displayed in the site header, footer, or sidebar |
Example: In the farmers market site example, you might put the hours and location in a sidebar block. |
|||
Taxonomy term |
Vocabulary |
Taxonomy module |
Used to classify other types of content |
Example: In the farmers market site example, you might classify Recipe content with an Ingredients taxonomy vocabulary, with taxonomy terms like Carrots and Tomatoes. In a blogging site, blog posts might be classified using a Tags vocabulary, and perhaps also a Categories vocabulary. |
|||
File |
(none) |
File module |
An image or attachment file that is tracked and managed by the site, often attached to other types of content |
Example: In the farmers market site example, both Recipe and Vendor pages might have image attachments, which would (behind the scenes) be managed as File entities by the site. |
|||
Contact form |
Form type |
Contact module |
A form that lets site visitors contact site owners |
Example: A contact form is needed in the farmers market site example. |
|||
What is a field?
Within entities, the data is stored in individual fields, each of which holds one type of data, such as formatted or plain text, images or other files, or dates. Field types can be defined by the core software or by modules.
Fields can be added by an administrator on entity subtypes, so that all entities of a given entity subtype have the same collection of fields available. For example, the Vendor content type in the farmers market example might have fields for the vendor name, a logo image, website URL, and description, whereas the Basic page content type might only have fields for the title and page body. When you create or edit entities, you are specifying the values for the fields on the entity.
3.4. Concept: Modular Content
Overview of modular content and how content in a page can be sourced from other content items.
What is modular content?
Given that the content of your site is stored in a database, it is desirable to make the content modular, meaning that certain pages on your site, rather than being edited as a whole page, are instead generated automatically from other content items. For instance, in the farmers market site scenario, you might create individual content items for recipes. If the recipe content items have a field that keeps track of ingredients, then your site could include a composite page that would list recipes, and allow visitors to search for a recipe that contained some particular ingredient they had bought at the market.
Smaller sections of pages can also be generated as composites. For instance, recipe content items could have a field that keeps track of which vendor submitted the recipe (see [structure-reference-fields]), with the vendor details edited in separate vendor content items. This would allow you to do the following on your site:
-
On each Recipe page, there could be an area that displays some information about the vendor that submitted the recipe, such as their name and market stall number.
-
Each vendor page could have a section that lists the recipes they have submitted.
The key idea is that each piece of information is only edited in one place. When vendor information is updated, all recipe pages that display that vendor information are automatically updated; when a recipe is submitted by a vendor, it is automatically displayed on the vendor page. The core Views module is the usual way to use modular content to create composite pages and page sections; see [views-concept] for more information. Also, view modes are useful for defining different ways to display each content item; see [structure-view-modes] for more information.
3.5. Planning your Content Structure
How to plan a content structure that assigns content entity types to specific content on the website.
Goal
Make a plan for the content structure of the site (which type and subtype of entity to use for which content), and which pages will contain listings of content.
Steps
-
Brainstorm about what content your site needs to contain, which could include content that visitors would be looking for, as well as content that you want to show to visitors. The result could be the description in Guiding Scenario.
-
For each identified piece of content, decide which content entity type would be the best fit. In doing this, you’ll need to consider where and how the content will be used and edited on the site. For example, in the farmers market site scenario, you might want to display the hours and location of the farmers market on the sidebar of every page. For that content, a single custom block makes sense. As another example, you might decide that pages displaying information about each vendor should be content items managed by the core Node module, because you want vendors to be able to edit their own listings. The core Node module permission system lets you do this easily.
These decisions do not necessarily always have only one right answer; for instance, you could decide that vendor pages should be user profiles instead of content items, but if you did that the content would be tied to a specific user account, and it would not be as easy to later change the ownership of a vendor page to a different user account.
-
Within each content entity type you identified, decide what division into entity subtypes would make sense. For example, in the farmers market site example, you would probably decide that under the Content item entity type, there should be one content type for basic pages (Home and About), one for vendor pages, and one for recipe pages.
-
For each entity subtype you decided on, decide what fields are needed. For instance, the Vendor content type might need fields for the vendor name, web page URL, image, and description.
-
Decide on what entity listings are needed, which could be entire pages or smaller areas on the page. For each listing, you’ll need to determine which entities should be listed. Then you’ll need to decide in what order and with what filtering options they should be displayed; for example, you might want to give the site visitor the option to search by keyword, to filter the list down to a subset, or to sort the list. You’ll also need to decide what information from the entities should be shown, which might result in adding to the list of fields you determined in the previous step. The farmers market site, for example, needs to have a Recipes listing page that lists content items of type Recipe, with the ability to filter by ingredients, so that means that the Recipe content type needs an Ingredients field.
-
For each identified field on each entity subtype, identify what type of data it should contain (such as plain text, formatted text, a date, an image file, etc.), and how many values should be allowed. Most fields are single-valued, but for example, a Recipe should allow for multiple values in its Ingredients field.
-
Consider which fields would be best as references to taxonomy term entities: fields whose values should be chosen from a list of allowed values. Allowed values that are expected to change and grow over time, are good candidates. An example is the Ingredients field for the Recipe content type.
-
Consider which fields should reference other content entities. An example is that since vendors will be submitting recipes, a field will be needed on the Recipe content type that references the Vendor content item for the vendor who submitted the recipe.
Here’s an example of the resulting content structure for the farmers market scenario example site:
| Entity type | Entity subtype | Examples | Fields |
|---|---|---|---|
Content item |
Basic page |
Home page, about page |
Title, page body |
Content item |
Vendor |
A page for each vendor at the market |
Vendor name, page body, image, URL |
Content item |
Recipe |
A page for each submitted recipe |
Recipe name, page body, image, reference to Vendor who submitted it, Ingredients taxonomy |
Custom block |
(generic) |
Copyright notice for footer, Hours and location for sidebar |
No special fields |
Taxonomy term |
Ingredients |
Carrots, tomatoes, and other recipe ingredients |
No special fields |
Contact form |
(generic) |
Generic contact form |
Name, email, subject, message |
User profile |
(none) |
Will not be displayed on site |
No special fields |
And here are the listings the site needs:
| Page or page area | Entity type and subtype | Filter/sort/pagination | Fields displayed |
|---|---|---|---|
Vendors page |
Vendor content items |
All vendors, alphabetical, paged |
Image, vendor name, trimmed body |
Recipes page |
Recipe content items |
Filter by ingredients, alphabetical, paged |
Image, recipe name |
Recent recipes sidebar |
Recipe content items |
List 5 most recent |
Image, recipe name |
Videos
Attributions
Written and edited by Jennifer Hodgdon and Grant Dunham.
3.6. Concept: Editorial Workflow
Overview of the editorial workflow to manage content on a website.
What is an editorial workflow?
An editorial workflow is the process organizations follow to create, review, edit, and publish content. Multiple people in different roles in the organization can be part of the process. For example, content creators could collect information and write content; editors could review, edit, ask for changes, and publish the content once it’s ready to be shared with the audience. Later on, content revisions could go through a simple process for small changes, or a more complex process with reviews for larger changes.
What tools are available for managing workflows?
- Published/Unpublished status
-
The Content item entity type supports marking each content item as either Published or Unpublished. Viewing permissions are separate for published and unpublished content; for example, all site visitors might be able to see published content items, while only content creators and editors can see unpublished content items.
- Revision tracking
-
Some content entity types support revision tracking, meaning that as content is revised, the software stores the older revisions, so that they can be compared or reverted.
- Workflows
-
The core Workflows module lets you define workflow states and transitions, beyond just having content be published or unpublished. The companion core Content Moderation module lets you assign permissions and roles to the workflow transitions. Both can be used with both Content item and Custom block entity types.
- Block placement
-
The Custom block content entity lets you create a custom block and edit it, but only make it visible on the site once it is ready.
Related topics
Attributions
Written and edited by Diána Lakatos at Pronovix, Grant Dunham, and Jennifer Hodgdon.
3.7. Concept: User Interface, Configuration, and Content translation
Overview of languages and translation on a site.
What languages does the software support?
The base language for the software that your site runs (core software, modules, and themes) is English. However, using this software you can create a site whose default language is not English, in which case anyone viewing the site should see only that language (assuming that the site is fully translated). You can also use this software to create a multi-lingual site, with a language switcher that site visitors can use to switch to their preferred language. You need to have the core Language module installed in order to use a language other than English on the site.
What can be translated on your site?
There are three types of information that you can translate, each with its own method for translating:
- User interface text
-
Built-in text present in the core software, modules, and themes. This can be translated from the base English language of the software into the language(s) of your site. Typically, rather than needing to translate this text yourself, you can download translations. You need to have the core Interface Translation module installed in order to translate this text, and the core Update Manager module installed in order to automatically download translations.
- Configuration text
-
Text whose structure and initial values are defined by the core software, modules, and themes, but that you can edit. Examples include the labels for fields in your content types, header text in views, your site name, and the content of automatic email messages that your site sends out. After creating configuration text in the default language of your site, you can translate it into other languages. For default configuration supplied by the core software, modules, and themes, translation is included with the downloads of user interface text translations. You need to have the core Configuration Translation module installed in order to translate this text.
- Content text and files
-
If your site is multilingual, you can configure the content fields on your site to be translatable. After creating content in one language, you can translate it into other languages. Fields can contain textual information or uploaded files, and for each field on each entity subtype, you can configure it to be translatable or non-translatable. You need to have the core Content Translation module installed in order to translate this text.
What information will remain in English on my site?
Even if the default language of your site is not English, you will still see English text on certain administrative pages used to manage configuration. The reason is that when you edit configuration, you are editing the base, untranslated configuration values; translating configuration is a separate operation. For example, if you visit the Menus administration page, you will see menu names in English (for the menus that were set up when you installed your site), and if you click an Edit menu link, you will be editing the English name and description of the menu. To edit the menu name in a different language, you would need to have the core Configuration Translation module installed, and use the Translate link to edit the translated menu information.
4. Installation
Overview of server requirements and details of common installation tasks.
4.1. Preparing to Install
How to download the core software and satisfy prerequisites for installation.
Prerequisite knowledge
-
How to install and configure server software (if installing on your own computer)
-
How to set up hosting for a generic web site
-
How to create a database
Site prerequisites
Server software must be installed on the computer where you plan to host your site. See Concept: Server Requirements for a list of requirements.
See Setting Up an Environment with DDEV for the recommended way to get started running the software locally.
Depending on how you plan to download the core software, you may need to install additional software tools first. See Concept: Methods for Downloading and Installing the Core Software and Concept: Additional Tools.
Steps
-
Choose methods for downloading and installing the core software, from those listed in Concept: Methods for Downloading and Installing the Core Software. The rest of these instructions apply to the Composer and manual download options; if you chose other options, like a one-click installer from a hosting provider, consult the relevant documentation for any additional steps.
-
Set up a URL and hosting for your site on the server. Verify that the hosting is working by putting a simple HTML file in the web root directory of the hosting, and visiting the URL for your site.
-
Create a database, along with a database user account with full access.
-
Download the core software files to the web root directory, using the method you decided on. See Concept: Methods for Downloading and Installing the Core Software for links to instructions.
Expand your understanding
See Running the Interactive Installer to run the interactive installer.
Additional resources
Attributions
Written and edited by Drew Gorton, Michael Lenahan at erdfisch, Jennifer Hodgdon, and Jojy Alphonso at Red Crackle.
4.2. Concept: Server Requirements
Overview of server requirements for installing and running the core software.
What are the requirements for running the core software?
Disk space
The total amount of disk space needed for your site is not a fixed amount, as it depends on your site. The base files for the core software take up about 100 MB on the web server. You will need more space if you install additional modules or themes, and you’ll also need space for media, backups, and other files generated by and uploaded to your site. The database also uses disk space, although that is typically not in the same area (and in some cases, not even on the same server) as that used by the site files.
PHP
PHP 8.3 or a higher PHP 8 version. PHP must be set up with a minimum memory size of 64MB; if you are running multiple modules on your site or using memory-intensive PHP-based command-line tools (such as Composer), considerably more memory than that may be needed.
Certain PHP extensions are also required; the exact list of required PHP extensions depends on how you install the core software and which modules you are using on your site. Generally, hosting service providers have installed all the PHP extensions you will need. If you are self-hosting or running your site on your local computer, you will get error messages during installation if any required PHP extensions are missing, and should be able to install them and continue. See PHP requirements for a complete list of requirements.
Web server
- Apache (Recommended)
-
Apache is the most commonly used web server. The core software will work on Apache 2.4.7 or higher hosted on UNIX/Linux, OS X, or Windows that have the Apache mod_rewrite module installed and enabled. The Apache VirtualHost configuration must contain the directive AllowOverride All to allow the .htaccess file to be used.
- PHP Local Server
-
You can temporarily run a local demo site on your computer using just PHP, without installing web server software.
- Nginx
-
Nginx is a commonly used web server that focuses on high concurrency, performance and low memory usage. The core software will work on Nginx 0.7 or greater hosted on UNIX/Linux, OS X, or Windows. The ngx_http_rewrite_module must be installed and enabled.
Database
Use one of the following databases:
-
MySQL - 8.0+ (MariaDB 10.6+, Percona 8.0+) or higher with an InnoDB-compatible primary storage engine
-
PostgreSQL - 16 or higher with the pg_trgm extension
-
SQLite - 3.45 or higher. Temporary local demo sites use SQLite, which is distributed as part of PHP and doesn’t require installing separate database software, but make sure your version of PHP has the minimum SQLite included.
Additional resources
Attributions
Adapted by Karl Kedrovsky, Brian Emery, and Jennifer Hodgdon, and Joe Shindelar at Drupalize.Me from "System requirements", copyright 2000-copyright_upper_year by the individual contributors to the Drupal Community Documentation.
4.3. Concept: Additional Tools
Overview of additional tools that help site builders conveniently create sites.
What tools are available for site builders?
There are several additional tools available that help you create sites faster, more accurately and with less effort.
- Drush
-
See below for more about command-line tools.
- Git
-
See below for more about version control tools.
- Composer
-
See below for more about Composer.
- Devel
-
The contributed Devel module helps with development tasks such as debugging and inspecting code, and generating dummy content.
What are command-line tools?
Command-line tools provide an alternative to using the administrative interface for various operations on your site. Many site builders and maintainers have invested the time to install and learn a command-line tool, because:
-
Administrative tasks are typically faster and less tedious when performed at the command line than in the user interface.
-
You can write scripts that combine site-related commands with other commands on the server, to automate more complicated tasks.
-
Command-line tools provide additional functionality not available via the administrative interface; for example, running database queries.
The most popular tool is Drush. Drush is a command-line interface and scripting tool that can speed up common tasks for developers, site builders, and DevOps teams. This guide documents commands from the latest stable version of Drush for many tasks; it does not document commands for older versions of Drush, but you can look them up in the Drush documentation.
To use these tools, you will need to have command-line terminal access to the environment where your website will be hosted, and you will need to install Composer first in order to install Drush.
To install Drush first make sure your project is using Composer to manage dependencies. See below for more about Composer. Then use the following commands:
# Install Drush composer require drush/drush
What is a version control system?
A version control system is software that keeps copies of files and revision history in a repository, and allows you to add, delete, and update files. For a web site project, revision control software can help you:
-
Test locally before deploying files on the live site
-
Look at, compare with, and revert to previous versions of files
-
Look at the added, changed, or deleted files before you commit the changes (update the repository)
-
Merge changes from different team members together
-
Keep files and configuration synchronized between local and live sites
There are many proprietary and open-source version control systems to choose from; a popular choice is Git, which is open-source software that runs on most computer platforms. Git is a distributed version control system that allows you to have one or more copies of your repository, which allows you to commit changes to a copy and then only push them to the repository you’ve designated as canonical when you’re ready to share them with others. The canonical git repository can be hosted on your local computer or a server at your company, but many software projects and individuals host their Git repositories using third-party services provided by GitLab or GitHub.
What is Composer used for?
Composer is a tool for managing PHP dependencies, where the developer specifies what version of each external library is needed, and Composer manages the process of downloading and installing the libraries.
Composer can be installed on the local development environment or webserver but is often already available in Drupal development tool kits.
The core software is a primary user of Composer, because it makes use of several externally-developed software libraries, which must be downloaded and installed in order for the core software to work. When you install the core software, you either need to download an archive that contains compatible versions of the external libraries, or you need to run Composer to download the external libraries after the initial download. The Drush command-line tool is also downloaded using Composer.
Some contributed modules also make use of externally-developed software libraries; for example, a Facebook integration module might require Facebook’s integration library to be installed for the module to work, and a geographical module might make use of a standard library of geographical functions. To install a module with external dependencies, you will need to run Composer.
What tools are available for module and theme developers?
In addition to the site builder tools mentioned above, the following tools are useful for module and theme developers.
- Drush
-
Drush is a command-line tool that can be used to generate boilerplate code and interact with a Drupal site. It can generate, for example, block or form code, install modules and themes, clear the cache, and create dummy content.
- Coder
-
Coder is a command-line tool that checks if your modules and themes comply with coding standards and other best practices. It can also fix coding standard violations.
- Browser debugging tools
-
Web browsers such as Firefox and Chrome include tools that allow viewing, editing, debugging, and monitoring CSS, HTML, and JavaScript. You can open the debugging pane or window by right-clicking the mouse in an area of your window, and choosing "Inspect" or "Inspect element".
Additional resources
Attributions
Written and edited by Boris Doesborg and Jennifer Hodgdon, and Joe Shindelar at Drupalize.Me. Some text adapted from "Introduction to Git", copyright 2000-copyright_upper_year by the individual contributors to the Drupal Community Documentation.
4.4. Concept: Methods for Downloading and Installing the Core Software
Overview of methods you can use to download the core software.
What methods are available for downloading the core software?
Before you can build a site, you will need to first download the core software. Depending on your plans, there are several ways that you can download the core software:
- Use Composer
-
If you plan to build a site, and continue to develop it over time you should use Composer to download the core software, because Composer will manage the dependencies properly. If you plan to use the Drush tool (see Concept: Additional Tools), using Composer is required. See Using Composer to Download and Update Files for instructions.
- Try a free online demo
-
If you are evaluating whether or not to use Drupal to build a site, you can use an online provider to get a demo installation of the core software in 20 minutes or less. See the Drupal.org page "Try Drupal".
- Use a one-click installer from your hosting provider
-
If you choose to install the core software at your hosting provider, your hosting provider may have specific documentation and/or a one-click install that you can use. See Drupal.org’s list of hosting providers that support Drupal.
- Use a pre-configured environment
-
Use a pre-configured environment or virtual machine that contains Drupal and all the required supporting software to install Drupal locally. See the section for your operating system under Drupal.org community documentation page "Local server setup guide" for possible options.
What happens when I install the core software?
Installing the core software means setting up some database tables, configuration, and an administrative user account, so that you can build and use your site.
What methods are available for installing the core software?
There are several ways to install the core software:
- Behind-the-scenes installer
-
If you choose to use an online demo or one-click installer from a hosting provider, the core software may be installed for you automatically.
- Interactive installer
-
The core software has an interactive installer that presents you with several on-line forms, and then completes the installation using the information you provide in the forms. See Preparing to Install and Running the Interactive Installer.
- Command-line tool
-
Command-line tools (see Concept: Additional Tools) can also be used to perform the installation steps.
- Demo site installer
-
Quickly create a temporary demo site that uses the built-in web server and SQLite database that are part of PHP by running the command below from the root directory of your project. In this case, you will not run the interactive installer. See the Evaluator Guide to learn more.
---- php -d memory_limit=256M core/scripts/drupal quick-start demo_umami ----
Attributions
Written and edited by Drew Gorton, Michael Lenahan at erdfisch, Jennifer Hodgdon, and Jojy Alphonso at Red Crackle.
4.5. Setting Up an Environment with DDEV
How to set up a development site using DDEV, a local development environment for PHP applications.
Goal
Set up a local development environment using DDEV to serve the application and Composer to download the required files.
Why use DDEV?
DDEV is a local development environment for PHP applications built on Docker. It includes all the necessary components to run the core software, and is used by many developers in the Drupal community.
Steps
-
Follow the official DDEV installation instructions to install DDEV on your local machine. DDEV is available for Windows, Mac, and Linux. The installation process is different for each operating system, so be sure to follow the instructions for your OS.
-
After installing DDEV, follow the Drupal Quickstart instructions to download the core software using Composer and install it in the DDEV environment.
-
Run the command
ddev launchfrom the directory created in the previous step to open the site in your web browser and confirm the environment is working correctly.
4.6. Using Composer to Download and Update Files
How to use the Composer tool to manage the files in the core software and add-on modules and themes.
Goal
Use Composer to download or update files and dependencies in the core software, or in add-on modules and themes.
Site prerequisites
If you want to use Composer, it must be installed either on a local development server or your live site. See Concept: Additional Tools.
Steps
If you are unable to install the Composer tool on your live server, you can follow the steps in any of the sections below on your local server, and then transfer any updated or added files to your live server. The recommended procedure is to make an archive or zip file of the new and changed directories, transfer the archive to your live server, delete the directories that have changed, and extract the archive. Make sure to check for updates and additions to the following files, in the root of your installation:
-
vendor directory
-
autoload.php
-
composer.json
-
composer.lock
Using Composer to download the core software
Follow these steps if you have not yet downloaded or installed the core software, and you want to use Composer to download both the core software and its external dependencies:
-
At the command line, change to one level above the directory where you want the software to reside.
-
Enter this command, where mydir is the directory you want to create:
composer create-project drupal/recommended-project mydir
-
The latest release of the core software will be downloaded to the mydir/web sub-directory.
Using Composer to download a module or theme
Follow these steps if you are already using Composer to manage the core software, and you want to use Composer to add a contributed module or theme with its dependencies.
-
Each time you want to add a contributed module or theme, determine the project’s short name. This is the last part of the URL of the project page; for example, the Geofield module, at https://www.drupal.org/project/geofield, has short name geofield.
-
To download the contributed module or theme, along with its external dependencies, enter the following command at the root of your site (substituting the short name of the module or theme for geofield):
composer require drupal/geofield
Using Composer to update previously-downloaded files
Follow these steps to update the files for the core software or a contributed module or theme, after having already started to manage dependencies with Composer:
-
Determine the short name of the project you want to update. For the core software, it is core. For contributed modules and themes, it is the last part of the URL of the project page; for example, the Geofield module, at https://www.drupal.org/project/geofield, has short name geofield.
-
If you want to update to the latest stable release, use the following command, substituting the short name of the project to be updated for geofield:
composer update drupal/geofield --with-dependencies
-
If you need a specific version, determine how to enter the version number you want to update to. For example, for version 8.x-1.16 of a contributed module, you would enter just the 1.16, and for the core software version 9.0.7, you would enter 9.0.7. Then enter the following command at the root of your site (substituting the short name of the project for geofield and the correct version number):
composer require drupal/geofield:1.16
Expand your understanding
You can learn more about Composer commands by using Composer’s built-in help
system. For example, to learn more about the create-project command, enter
composer help create-project in your command window.
Additional resources
Attributions
Adapted by Jennifer Hodgdon, Hans Fredrik Nordhaug, and Joe Shindelar at Drupalize.Me from "Using Composer to manage Drupal site dependencies", copyright 2000-copyright_upper_year by the individual contributors to the Drupal Community Documentation.
4.7. Running the Interactive Installer
How to use the interactive installer to install the core software.
Site prerequisites
Note that if you followed the instructions in Setting Up an Environment with DDEV the core software
was already installed. If you wish to install the core software again, you can
run the command ddev drush sql:drop and then follow the instructions below.
Steps
-
If you are using a 1-click install from a hosting provider or demo site, you will most likely see some or all of the following screens as part of the installation process. If you uploaded the core files manually or using Composer, to start the installer, open a browser and visit the URL that you set up for your hosting.
-
Select a language on the first page of the installer; for example, English. You could optionally choose from any of the other listed languages. The language files for the chosen language will be downloaded and installed so that the rest of the installation process can be finished in the chosen language. After choosing a language, click Save and continue.
-
Select an installation profile. Installation profiles provide site features and functions for a specific type of site as a single download containing the core software, contributed modules, themes, and pre-defined configuration. Core contains two installation profiles. Select the core Standard installation profile. Click Save and continue.
-
The next step in the installer will verify that your system meets the minimum requirements. If it does not, you’ll be presented with an outline of what needs to be corrected in order to proceed. If it does, the installer will automatically advance to the next step.
-
Provide details of the database you created in the Preparing to Install chapter. Then click Save and continue.
Field name Explanation Value Database name
The custom name given to the database
drupal
Database username
Username created
databaseUsername
Database password
Password chosen
**
-
The next step will display a progress bar under the heading Installing Drupal. After the installer has completed, it will automatically advance to the next step.
-
The next step is to configure some basic information about your new site (also notice if there is a warning about file permissions, for a later step). Note that the user account you create in this step is the site’s admin account. See [user-admin-account] for important information about this unique account. You can safely name this account "admin", and make sure to choose a secure and unique password.
Fill in the form with the following information:
Field name Explanation Value Site name
The name chosen for the site
Anytown Farmers Market
Site email address
The email associated with the site
Username
The designated user’s credentials
admin
Password
The password chosen
**
Confirm password
Repeat the password
**
Email address
The user’s email
The remaining fields can likely be left at their default values.
-
Click Save and continue.
-
You will be redirected to the front page of your new site and you should see the message Congratulations, you installed Drupal! displayed at the top of the page.
-
You may have seen a warning in the Configuration step about file permissions, and you may continue to see this warning until you fix the permissions. To avoid the warning and make your site more secure, change the permissions on the sites/default directory and the sites/default/settings.php file so that they are read-only (you may need to consult your hosting company documentation about how to do that).
Expand your understanding
Alternatively, you can install the software using Drush instead of the UI. Use the following Drush command, from inside the directory that you downloaded the software to, where DB_NAME, DB_USER and DB_PASS are your database’s credentials:
drush site:install standard --db-url='mysql://DB_USER:DB_PASS@localhost/DB_NAME' --site-name=example
Check the Status Report to see if there are any problems with the installation. See [prevent-status].
Additional resources
Attributions
Written and edited by Joe Shindelar at Drupalize.Me, and Jojy Alphonso at Red Crackle.
5. Basic Site Configuration
Overview of basic site configuration concepts. Tasks on module installation, user account settings, and themes are covered.
5.1. Concept: Administrative Overview
Overview of administrative menu and contextual links.
What is the administrative menu?
The toolbar provided by the core Toolbar module displays the Manage administrative menu at the top or left side of the site, for users with permission to see it. This menu provides access to all of the administrative areas of the site. The menu links will vary depending on which modules are active on your site and the permissions of the person viewing the menu; if you install using the core Standard installation profile and have full administrative permissions, the top-level links are as follows:
- Content
-
Lists and manages existing content, and allows creation of new content.
- Structure
-
Contains a list of links for managing structural elements of the site, such as blocks, content types, menus, and taxonomy.
- Appearance
-
Manages themes and appearance-related settings.
- Extend
-
Manages the installation and uninstallation of modules.
- Configuration
-
Contains links to settings pages for various site features.
- People
-
Manages users, roles, and permissions.
- Reports
-
Contains links to logs, update information, search information, and other information about the site’s status.
- Help
-
Lists help topics for installed modules that provide them.
The arrow button on the far right side of the second line of the toolbar (or far left side, if the site is being viewed using a right-to-left-reading language like Arabic) can be used to switch the menu from appearing horizontally at the top of the page, to a vertical format on the left side (or right side, in right-to-left languages). When viewed vertically, the menu becomes an interactive tree.
This guide has a standard way to describe navigation to administrative pages using the administrative toolbar. See Conventions of the Guide for more information.
What are contextual links?
Some administrative and editing functionality on the site can be accessed through the contextual links displayed by the core Contextual Links module. Contextual links take you to some of the same pages that you can access through the administrative menu, but instead of having to navigate through the menu hierarchy, these links are provided near where the related content is displayed on your site.
Contextual links have to be activated to be visible. If your site’s theme uses the default styling for contextual links, a pencil icon is used to indicate that contextual links are present and activated, and if you click the icon, you will see the contextual links. There are two ways to activate the pencil icons that provide access to the contextual links:
-
If you are using a mouse in a browser, the icon will temporarily appear when you hover over an area that has related contextual links.
-
You can click the master pencil icon (or its Edit link) at the right end of the top bar in the toolbar, which will activate all of the contextual links on the current page. This icon is only visible on pages with contextual links.
Attributions
Written by Scott Wilkinson and Jennifer Hodgdon.
5.2. Editing Basic Site Information
How to edit basic site information (site name, slogan, and default time zone).
Steps
Configuring the basic site information
-
In the Manage administrative menu, navigate to Configuration > System > Basic site settings (admin/config/system/site-information) to change the Site name, Slogan, administrative Email address, or the Default front page path.
-
Fill in the available fields as appropriate for your site.
Field name Explanation Example value Site details > Site name
Used to identify the site and displayed in browsers
Anytown Farmers Market
Site details > Slogan
How this is used depends on your site’s theme. Not displayed by default when using the Olivero theme.
Farm Fresh Food
Site details > Email address
Used as From address in automated email messages (registrations, password resets, etc)
-
After editing the fields, click Save configuration to see the changes applied to the site.
Configuring default Regional settings
-
In the Manage administrative menu, navigate to Configuration > Regional and language > Regional settings (admin/config/regional/settings).
-
Fill in the form as follows:
Field name Explanation Example value Locale > Default country
The primary country for your site
United States
Locale > First day of week
The day when the week starts on calendars
Sunday
Time zones > Default time zone
The primary time zone for your site
America > Los Angeles
Time zones > Users may set their own time zone
Whether logged-in users can choose a different time zone for display of dates and times on the site
Unchecked
-
After editing the fields, click Save configuration to see the changes applied to the site.
Additional resources
Attributions
Written and edited by Sree Veturi, Michael Lenahan at erdfisch, Antje Lorch, Jennifer Hodgdon, and Joe Shindelar at Drupalize.Me.
5.3. Installing a Module
How to install a core or contributed module, using the administrative interface or Drush.
Goal
Install a core module, or a contributed module whose files have already been uploaded to the site, through the administrative interface or using Drush.
Site prerequisites
If you want to use Drush to install modules, Drush must be installed. See Concept: Additional Tools.
Steps
You can use the administrative interface or Drush to install modules.
Contributed modules are not included with the core software must first be downloaded using Composer. See Using Composer to Download and Update Files for more information.
Using the administrative interface
-
In the Manage administrative menu, navigate to Extend (admin/modules). The Extend page appears showing all the available modules in your site.
-
Check the boxes for the module or modules you want to install. For example, check the box for the core Ban module.
-
Click Install. The checked modules will be installed.
Using Drush
-
In the Manage administrative menu, navigate to Extend (admin/modules). The Extend page appears showing all the available modules in your site.
-
Find the machine name of the module you want to install, by expanding the information area for the module. For instance, the core Ban module’s machine name is ban.
-
Run the following Drush command to install the module:
drush pm:enable ban
Expand your understanding
If you do not see the effect of these changes in your site, you might need to clear the cache. See [prevent-cache-clear].
Additional resources
Attributions
Written and edited by Boris Doesborg and Jennifer Hodgdon, and Joe Shindelar at Drupalize.Me.
5.4. Uninstalling Unused Modules
How to uninstall modules to reduce overhead.
Goal
Uninstall the core Search and History modules, as well as the core Ban module if you installed it in Installing a Module, to reduce overhead.
Site prerequisites
-
You must have at least one unused module on your site that you want to uninstall, such as the core Search module.
-
If you want to use Drush to uninstall modules, Drush must be installed. See Concept: Additional Tools.
Steps
You can use the administrative interface or Drush to uninstall modules.
Using the administrative interface
-
In the Manage administrative menu, navigate to Extend > Uninstall (admin/modules/uninstall) where you will find the list of modules that are ready to be uninstalled.
-
Check the boxes for the modules you are uninstalling (Ban, History, and Search). Click Uninstall at the bottom of the page.
You cannot uninstall a module if it is required by some other module(s) and/or functionality. For example, the core File module is required by the core Text Editor, CKEditor, and Image modules. It can’t be uninstalled unless you uninstall its dependent module(s) and functionality first. A module that cannot be uninstalled yet will have a disabled checkbox, restricting you from uninstalling it.
-
Step 2 will prompt you to confirm the module uninstall request. Click Uninstall.
Using Drush
-
In the Manage administrative menu, navigate to Extend (admin/modules). The Extend page appears showing all the available modules in your site.
-
Find the machine name of the module you want to uninstall, by expanding the information area for the module. For instance, the core Ban module’s machine name is ban.
-
Run the following Drush command to uninstall the module:
drush pm:uninstall ban
Expand your understanding
-
You can also uninstall the core Comment module by following these steps, but only after comment fields have been removed, which is a side effect of [structure-content-type-delete].
Videos
Attributions
Written and edited by Joe Shindelar at Drupalize.Me, Surendra Mohan, and Jojy Alphonso at Red Crackle.
5.5. Configuring User Account Settings
How to change user account registration settings.
Goal
Turn off the ability for people to register user accounts on the site. Also, review and/or edit the email messages generated by the site for events related to user accounts.
Steps
-
In the Manage administrative menu, navigate to Configuration > People > Account settings (admin/config/people/accounts).
-
Under Registration and cancellation, select Administrators only as the people with permissions to register user accounts. You can check Require email verification when a visitor creates an account in case you want to change the settings for account registration later on.
-
Optionally, change the default email address from which user account notifications from the farmers market website will be sent. This will help you maintain a separate email address from the one used for the website in general. For example, this email address for user account notifications will be useful for a staff member(s) communicating with vendors.
-
Optionally, edit the email templates under Emails to customize automated emails. There are several email templates provided by the core software. They are meant for different user-specific occasions. All of them can be personalized and three can be disabled via checkboxes: activation, blocking, and cancellation.
You can send out your own text (for example, welcoming the new vendors for whom accounts were just created) by editing the Welcome (new user created by administrator) template.
-
Click Save configuration to save the changes.
Related concepts
See Managing User Accounts for more information about user accounts and permissions.
Additional resources
Securing your site can help you with a more safety-focused approach to configuration.
Attributions
Written and edited by Laura Vass at Pronovix, and Jojy Alphonso at Red Crackle. config-theme.asciidoc
6. Basic Page Management
Overview of page management concepts. Tasks on content items, in-place editing, and menus are covered.
7. Setting Up Content Structure
Overview of content structure concepts. Tasks on content types, taxonomies, and reference fields are covered.
structure-content-type.asciidoc structure-content-type-delete.asciidoc structure-fields.asciidoc structure-reference-fields.asciidoc structure-taxonomy.asciidoc structure-taxonomy-setup.asciidoc structure-adding-reference.asciidoc structure-widgets.asciidoc structure-form-editing.asciidoc structure-view-modes.asciidoc structure-content-display.asciidoc structure-image-styles.asciidoc structure-image-style-create.asciidoc structure-image-responsive.asciidoc structure-text-formats.asciidoc structure-text-format-config.asciidoc
8. Managing User Accounts
Overview of user account concepts and details of common user account tasks.
12. Extending and Customizing Your Site
Overview of site customization and development. Tasks on downloading modules and themes are covered.
extend-module-find.asciidoc extend-maintenance.asciidoc extend-module-install.asciidoc extend-theme-find.asciidoc extend-theme-install.asciidoc extend-manual-install.asciidoc install-dev-sites.asciidoc install-dev-making.asciidoc extend-deploy.asciidoc extend-config-versions.asciidoc extend-git.asciidoc
13. Preventing and Fixing Problems
Overview of cache, data backup, and log concepts. Task on clearing the cache is covered.
14. Security and Maintenance
Overview of security and maintenance concepts. Tasks on updating the core software, modules, and themes are covered.