Beginner’s guide to Craft CMS [part 1]
tl;dr — your first website built with Craft CMS with a local setup and a deployed application.
Intro
Hei! Craft CMS is a powerful content management system and it lets you do everything the way you want it to, with little constraint. However, when first starting out with a framework, I like a bit of guidance, which I missed in existing blogs and tutorials, so this will be an opinionated tutorial to kickstart your Craft CMS endeavours.
Part 1 is the configuration part where we get everything ready for part 2 where you’ll build your first website (and deploy it) using the features and perks of the aforementioned.
For who?
People who want to get started with Craft CMS and desire a clear example of how to set it up and dive in quick and dirty. Re-evaluating some decisions afterwards of course 😉. I’m working with near 20/20 hindsight after my first experience touching Craft CMS so you should be golden.
What are we ending up with
You will have a local setup of Craft CMS v3
with a (albeit very basic) fully functional website which is “mirror-deployed” on Fortrabbit live for the whole world to see 🙀
Prerequisites
- Basic knowledge of HTML
- Basic understanding of how to use Git
- Feel comfortable using the ‘terminal’ 😎
- Your favorite code editor (I’ll use Visual Studio Code)
- Have a unix system (so sorry)
Well that’s like… nothing
You’re quit right, only downside is that the configuration will take all of part 1 of this tutorial to get Craft running and that’s, well, boring. But trust me and pull through, it’s worth it.
1. Install and configure the web server
Download the free version of MAMP and fire it up. Go to Preferences>Ports and select Set Web & MySql ports to 80 & 3306.
Create a database
After you clickStart Servers a website will be pop up where you can go to phpMyAdmin. If the page doesn’t appear, go to http://localhost/MAMP/
Once in the admin panel, create a database called ‘tutorial’.
Add MAMP to your path
Next we’ll add the PHP and MySQL versions of MAMP (the most simple setup) to your bash profile. Below is my example, just change the php version (7.2.8 in my case) with yours.
$ echo 'PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php/php7.2.8/bin:${PATH}"' >> ~/.bash_profileNote: Restart your terminal or source the bash profile to activate changes to the file
You can check if it worked with:
$ which php
/Applications/MAMP/bin/php/php7.2.8/bin/php2. Install Craft
Composer
To create a Craft project we need Composer. The package manager of PHP. Not unlike npm for Node. Speaking of package managers, if you use Homebrew this step is as easy as:
$ brew update
$ brew install composer
...
$ composer -v
______
/ ____/___ ____ ___ ____ ____ ________ _____
/ / / __ \/ __ `__ \/ __ \/ __ \/ ___/ _ \/ ___/
/ /___/ /_/ / / / / / / /_/ / /_/ (__ ) __/ /
\____/\____/_/ /_/ /_/ .___/\____/____/\___/_/
/_/
Composer version 1.8.0 2018-12-03 10:31:16If composer isn’t added to your path, execute:
$ echo 'export PATH="~/.composer/vendor/bin:$PATH:$(yarn global bin)"' >> ~/.bash_profileIf I look at my .bash_profile file I’ll see these two lines (as well as anything else I’ve customised):
$ cat ~/.bash-profile
...
export PATH="~/.composer/vendor/bin:$PATH:$(yarn global bin)"export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php/php7.2.8/bin:${PATH}"
Now, go to Mamps’s htdocs folder in your terminal.
$ cd /Applications/MAMP/htdocsOnce arrived, issue following command:
$ composer create-project craftcms/craft my-firstThe last part is the name of the application you’re creating. The terminal should respond after a short while with the following
Welcome to Craft CMS! Run the following command if you want to setup Craft from your terminal:/Applications/MAMP/htdocs/my-first/craft setup
Run the setup wizard in the terminal
In your terminal, go to your project’s root directory and run the following command to kick off the Setup Wizard:
$ cd my-first
$ ./craft setupOh boy, an interactive terminal conversation takes off. Not to worry, here’s a cheat sheet.
Which database driver are you using? [mysql,pgsql,?]: mysql
Database server name or IP address: [localhost]
Database port: [3306]
Database username: [craft]
Database password: *******
Database name: [tutorial]
Database table prefix:You can see I used craft as the Database username. That’s because I created a separate user for this one (which you can do too). The default u and p are root and root… that’s why. The db prefix stays empty.
Username: [admin]
Email: your@email.com
Password: ******
Confirm: ******
Site name: My First
Site URL: [@web]
Site language: [en-US]Next, configure the web server to host your Craft project. Its document root should point to your web/ folder of the newly created project
Make haste and navigate to localhost in you browser of choice. You should see the following result:
Congratulations! 🎊 🎉
Now that we have everything in place to manage the content of them systems 😏, it’s time to show what Craft can do 💪.
3. Creating our application
Before we dig into the control panel in part 2, we’re going to get our own template and adapt it for Craft. For the purpose of this tutorial we are not going to bother too much with the styling of the interface and use a simple template. You can find it here:
https://startbootstrap.com/themes/clean-blog/
Be sure to put it somewhere you can easily access the folder for some good ol’ ✂️📋.
Layout
As mentioned above, we are not going to spend too much time covering this aspect. But let me know in the comments if you want some more in-depth coverage.
Start by going into /web and create a new folder called assets and copy following folders from the template to their new home:
css/
img/
js/
vendor/Replace the index.html in /templates with the one from our downloaded template and change the extension to index.twig. More on this later.
Your localhost should look like this:
🌸 Beautiful, I know.
Craft leverages the template engine from Symfony known as Twig. The syntax is easy to learn/use and has been optimized to allow developers to get their job done fast without getting in their way.
Here’s an example of an altered reference to a source file:
Original:
<link href="css/clean-blog.min.css" rel="stylesheet">
<script src="js/clean-blog.min.js"></script>Altered:
<link href="{{ alias('@web/assets/css/clean-blog.min.css') }}" rel=”stylesheet”>
<script src="{{ alias('@web/assets/js/clean-blog.min.js') }}"></script>
In Craft, /web acts as the public folder and has an alias @web and because our files are stored in web/assets we prefix the files with the alias. Change all the locally-referenced sources accordingly. Refresh the page and all source files should be loaded correctly (ignore the banner image for now).
Do this for all references. (end result below)
Let’s to keep it dry and separate the reusable bits . In templates create _layout.twig and copy/paste the content of index.twig
Note: files prefixed with an underscore are excluded from route mapping. It’s good practice to prefix all your partial files.
Next, in _layout.twig cut everything inside<body> except the <script> tags and add a body block.
As you can probably guess, the part you removed in _layout.twig is what we want to have left in the index file. To reference the layout from _index.html, at the top we state that we want to extend our _layout.twig and get our content inside that body block. You end up with the following:
After this, your project structure should look like the part1 branch of this repository:
On to part deux!
— will be published shortly
Let me know if you found this tutorial useful and if there’s something you want to know more about in the comments.
