Learning Code

In order to use a CMS locally on the computer, we need to run PHP, work with a database, and have a local "test server". All of this lets us preview and edit our pages directly in the browser. We're using Local, a localhost with PHP/Database access that is intended to be used with Wordpress but can be adjusted to use with the CMS of our choice. Local is free to use.

When the website is ready to go live, the local database is imported to the webhost and then relevent paths/names are updated.

Local Project - Initial Setup +

Open the Local app (F4 -> Local)
Close or skip any "login" dialogs (we don't need an account for the functionality we are using)
If the folder tab doesn't open automatically, click it
Click on "Create a new site"
Choose a site name - this will create a folder in your home directory, inside of a new "Local Sites" directory and choose "Continue"
Fill in temporary username/password info for Wordpress (you will delete Wordpress later, so the actual info doesn't matter) and choose "Continue"
Change to "Custom"
1. Set the highest version number for PHP & MySQL
2. We are adding PHP, a server-side language, to our site
3. MySQL is for working with a database
4. Choose "Apache" for the local host
5. Click on "Continue"
Local will do some installation and ask for an admin password - let me know when you reach this stage
Enable SSL:
1. Under Overview, next to SSL, click on "Trust"
2. At this point, it should ask for an admin password - ask for help
3. Open "Keychain Access" (F4 -> search for "Keychain")
4. Under System Roots -> Certificates, search for "local"
5. Double-click on your-site-name.local
6. Expand "Trust"
7. Change "When using this certificate" to "Always Trust"
8. Close the dialog and ask for help (you'll need an admin password) — this should be the last time

Replacing Wordpress & Adding Your Site +

Since we aren't using Wordpress, delete the Wordpress files:
1. Click on "Site Folder" at the top under your site name (That will open Finder)
2. Drag the "Local Sites" folder to the Favorites sidebar for easy access later on
3. In the new Website folder, go to "app" → "public"
4. Delete all the files/folders in the "public" folder
  1. With any file in the public folder selected, press CMD+A to select all of them
  2. Either right-click on the selection and choose "Move to Trash" OR drag and drop them over the Trash can icon in the Dock
We also need to empty the database to use with Couch instead:
1. Back in Local, click on the "Database" tab
2. Click on "Open AdminerEvo" (this lets us edit the database that was created for us)
3. Sometimes the first open fails, just make sure the server has started and try again if needed
4. Click on the empty checkbox next to the "Table" two select all of the database tables
5. Click on "Drop" to delete the tables
6. If a dialog asks "Are you sure" or something to that effect, choose "OK"
In Finder, go back to the "public" folder for your Local site & add in:
1. The couch directory
2. Your website files (html, css, & images)
In Brackets, open the "public" folder for the Local website

Using Local for Preview +

Going forward, you will use Brackets to make any edits to the code and Local to preview those changes and add in actual content with CouchCMS in the browser.

Whenever you open Local, click on your website in the left sidebar
On the top-right, click on "Start Site"
Click on "Open Site" to preview your site in the browser
Use Brackets normally (make sure the "public" folder is open)
Save-All (Opt+Cmd+S) whenever you are done making changes
Use CMD+R in the browser to reload the saved changes

If you log out without stopping the site in Local, you'll see a warning notification. It's fine to let the computer stop the server for you.

With Couch CMS, you can add CMS functionality as you are coding your site - or at the end and retrofit the site. Either way, the webpages will need to be saved in the PHP format - ie. index.php or about.php.

On PHP pages, write your HTML just like normal. When we add PHP for our CMS functionality, it'll always be added within:
<?php some code(); \?>

Brackets can't do a live preview of PHP directly. While we should be able to connect it to our local server, it doesn't seem to work. However with Local servers running, we can see saved changes in the browser using the URL:
your_website_folder_name.local.
Just reload whenever there are new saved changes.

Setting up Couch +

When ready, download CouchCMS from our class server:
1. In Finder, click on "abarchive" in the sidebar
  1. If it's not there, use the "Go" menu, and find "Connect to Server"
  2. Change "smb://abfs01" to "smb://abarchive" and click on "Connect"
  3. Choose the "Web Design" class folder and choose "OK"
2. From the Web II folder, drag and drop CouchCMS onto your comuter
3. Double-click on CouchCMS to unzip it
4. In the CouchCMS folder, find the "couch" folder and move or copy it into your website folder in htdocs
Run through the initial couch setup:
1. In Brackets, open your htdocs website folder (File → Open Folder)
2. In the bottom of the Brackets sidebar, expand the couch folder
3. Find and rename "config.example.php" to "config.php"
  →
4. Open config.php
5. Enable secure HTTP:
  1. Uncomment line 14 by deleting the 2 "//"
  2. Replace the url with 'https://your-site-name.local' (this will be replaced with the real URL when using an actual web host)
6. Replace the following with the information from Local
  1. database_name - 'local' (this will be replaced with a custom database name when using an actual web host)
  2. database_username - 'root' (this will be replaced with a custom username when using an actual web host)
  3. database_password - 'root' (this will be repaced with an actual password when using an actual web host)
7. Save the changes
8. Go to the couch cms install page in the browser:
  1. In the browser, change the URL to your website's couch folder:
    localhost/your_website_folder_name/couch
9. Create your Couch CMS account info:
  1. Choose a username - this should be professional sounding if this is a client website
  2. Use your school email
  3. Choose a password you will remember
  4. Write down your login info just in case
Enable inline editing for a more polished client experience:
1. In the couch/addons folder, rename "kfunctions.example.php" to "kfunctions.php"
  →
2. Open "kfunctions.php" in Brackets (or etc.)
3. Remove the comment from "//require_once( K_COUCH_DIR.'addons/inline/inline.php');"
  ↓
4. Save the change

Enable Couch on Each Page +

Edit each page to add CMS capability:
1. Choose a page - ie. index.html and rename it to use .php - ie. index.php
  →
2. Open the php page in Brackets or etc.
3. Enable couch functionality on the page:
  1. Add the php require above the HTML element (the very top of the page)
```
  <?php require_once('couch/cms.php'); ?> 
  <html>
  

 
```
  2. In the head element (directly before the closing tag), add:
    (This enables inline editing for the page)
```
  	<cms:load_edit /> 
  </head>
  
```
  3. At the end of the page, after the HTML element, add:
```
  </html>  
  <?php COUCH::invoke(); ?>  
  
```

Editable Regions +

Once the basic couch functionality is setup, editable regions can be added to the HTML. They'll display on the backend when you are signed into Couch. Afterwards, inline or pop-up editing can be added when on-page editing is needed.


  <section>
  	<cms:editable name='unique_name' type='text' label='Name For the Backend'>Temporary placeholder content can go here </cms:editable>  
  </section>

name - a unique identifier that allows you to access the editable region elsewhere in the HTML
label - the name that displays for the backend
type - the kind of content

Sometimes there's no placeholder content, and in those cases, just use a single tag:


  <section>
  	<cms:editable name='unique_name' type='text' label='Name For the Backend' />  
  </section>

There are a variety of types but the ones we'll use most often include:

image
text - for a single line
richtext - for large areas of text
file - necessary for SVG

Editable regions can be displayed anywhere on the page - as many times as you want using cms:show. Just make sure to use the same name.


  <section>
  	<cms:editable name='unique_name' type='text' label='Name For the Backend'>Temporary placeholder content can go here </cms:editable>
	<cms:show unique_name />
  </section>

To see your editable regions on the backend, you may need to "View Site" (reload if already open) and then reload the backend.

Inline Text Editing +

Inline editing can be added to editable regions so that they can easily be edited directly on the page, when signed in.

Make an editable region like normal:


  <section>
  	<cms:editable name='unique_name' label='Name For the Backend'></cms:editable>  
  </section>

INSIDE the opening tag for the parent/containing element, add cms:inline_edit (use the same name as the editable region - this links them together):
```
  <section <cms:inline_edit 'unique_name' /> >  
  
```
Save the changes to the page
View the page in the browser then reload the CouchCMS backend page
You can edit the text:
- In the backend, just click on the page in the sidebar, type the text in the field, and save
- Alternatively, from the bottom of the couch interface, click on "View Site" and edit directly on the page - make sure to press the save icon to commit the changes

Pop-up Text & Image Editing +

Pop-up editing can be added for a variety of 'types' - just set the correct type in the cms:editable. This is the only way to make images editable for on-page editing.

Make an editable region like normal - for an image this would be:
(Adding the hidden attribute hides the path to the image - otherwise the path displays along with the image)
```
  <cms:editable name='img_name' label='Backend Name' type='image' hidden='1' /> 
					    
```
If necessary, add cms:show (images need this to replace the image path):
```
  <img src="<cms:show img_name />" />
					   
```

Add pop-up capability:


  <cms:editable name='img_name' label='Backend Name' type='image' hidden='1' />
  <img src="<cms:show img_name />" /> 
  <cms:popup_edit 'img_name' />

The image can be added from the edit button when signed in on the front end, or on the backend - either way, just double-click on the image icon once it's been uploaded to couch to select the image

Keep in mind that multiple elements can be placed into a single pop-up. To do so, add multiple names in the field, with a | between each name:


  <cms:popup_edit fields='img_title | img_name | some_text' />

The "edit" button can be styled by using the .k_inline class, if needed. This can be a good place to use absolute positioning to have a little more control over where the edit button displays. Make sure that the font size, weight, and color are all consistent.

SVG Images +

A couple changes need to be made to upload/display SVG images through the CMS. By default they are not enabled.

Enable SVG images to be uploaded:
1. Open couch/includes/fileuploader/config.php
2. Search (with CMD+F) for 'AllowedExtensions'
3. Add "svg" to the image, media, and file extension lists
Enable SVG images to be displayed:
1. Open couch/includes/kcfinder/config.php
2. Search (with CMD+F) for 'allowedExts'
3. Under 'allowed Exts', add "svg" to the image and file extension lists

Add the code for pop-up editing like normal, but use 'file' for the type instead of image


  <img src="<cms:show img_name />" /> 
  <cms:popup_edit 'img_name' />
  <cms:editable name='img_name' label='Backend Name' type='file' hidden='1' />

Repeatable Regions +

Repeatable regions are super helpful - they allow your client to duplicate and re-arrange regions with similar types of content. Ie. staff photos, captions or etc. Keep in mind that repeatable regions ignore inline editing, so we'll need to enable pop-up editing for any text to be able to edit on the front end.

Making something repeatable:

Around the editable region(s) add:


  <cms:repeatable name='multi_img' >
    <cms:editable type='image' name='img_name' /> 
    <cms:editable type='nicedit' label='Description' name='some_name' />
  </cms:repeatable>

Make the repeatable region visible by adding cms:show_repeatable around cms:show:


  <cms:repeatable name='multi_img'>
    <cms:editable type='image' name='img_name' /> 
    <cms:editable type='nicedit' label='Description' name='some_name' />
  </cms:repeatable>
  <cms:show_repeatable name='multi_img'>
    <img src="<cms:show img_name />" /> 
    <p><cms:show some_name  /> </p>
  </cms:show_repeatable>

Enable Pop-up editing for front end editing:


  <cms:repeatable name='multi_img'>
    <cms:editable type='image' name='img_name' /> 
    <cms:editable type='nicedit' label='Description' name='some_name' />
  </cms:repeatable>
  <cms:show_repeatable name='multi_img'>
    <img src="<cms:show img_name />" /> 
    <p><cms:show some_name  /> </p>
  </cms:show_repeatable>
  <cms:popup_edit fields='multi_img' />

When signed into the the backend, there'll be a "+" button to add new regions, a trash icon to remove a region, and drag/drop capability to reorder regions

On Page Navigation +

For a pageless site design, where navigating to different sub-sections of a page is needed, we can make the section heading editable - and then use that name as an id in order to navigate to that section from the menu.

Make a heading editable, like normal:


  <article>
	<h2  <cms:inline_edit 'unique_name' /> >
  	<cms:editable name='unique_name' label='Name For the Backend' type='text'></cms:editable>  
  </h2>
  </article>

Add cms:show to load that editable text as an id name:


  <article id="<cms:show unique_name />">
	<h2 <cms:inline_edit 'unique_name' /> >
  	<cms:editable name='unique_name' label='Name For the Backend' type='text'></cms:editable>  
  </h2>
  </article>

Use cms:show as the path and name for the menu's link


  <nav>
	<a href="#<cms:show unique_name />">  
	    <cms:show unique_name />
	</a>
  	<a href="#"></a>
	<a href="#"></a>
  </h2>
  </nav>

Showing/Linking to Specific Repeatable Region Content

Create the repeatable region like normal:


  <cms:repeatable name='multi_img'>
    <cms:editable type='image' name='img_name' /> 
    <cms:editable type='text' label='Picture Name' name='some_name' />
  </cms:repeatable>
  <cms:show_repeatable name='multi_img'>
    <img src="<cms:show img_name />" /> 
    <p><cms:show some_name  /> </p>
  </cms:show_repeatable>
  <cms:popup_edit fields='multi_img' />

Add cms:show_repeatable around cms:show where you are using it for ids/paths and etc:
```
  <nav>
	<a href="#<cms:show_repeatable 'multi_img' limit='1' offset='0'><cms:show some_name /></cms:show_repeatable>">  
	    <cms:show_repeatable 'multi_img' limit='1' offset='0'><cms:show some_name /></cms:show_repeatable>
	</a>
  	<a href="#"></a>
	<a href="#"></a>
  </h2>
  </nav>
  <article id="<cms:show_repeatable 'multi_img' limit='1' offset='0'><cms:show some_name /></cms:show_repeatable>">
  
```
- CMS:show_repeatable should use the same name as the repeatable region
- Limit determines how many repeatable regions can display - in this use case we only want 1 region
- Offset controls which region(s) display - 0 starts with the 1st region, 1 starts with the 2nd region & etc...
- CMS:show should use the same name as the specific editable field
- Make sure not to have any extra spaces around the cms:show shortcode
- Pay close attention to whether or not there should be quotes

CMS:show can be used to display any editable element multiple times. This is great for ids/linking but could also be helpful for showing thumbnail images in a gallery or etc...

Like always, you can add multiple regions into the same pop-up by using multiple names in the field, with a | between each name:


  <cms:popup_edit fields='multi_title | multi_img | multi_paragraph' />

Text Editor Tools +

The text editors can be customized to show different selections of tools, when working with the "richtext" type. Toolbars include:

basic - only very basic formatting
medium - adds alignment options, images and more
full - every tool option is enabled
custom - combines with custom_toolbar to choose your own list of tools


  <cms:editable type='richtext' label='About Me' name='about_text'toolbar='basic' />

When using the custom toolbar, there is a long list of tools that can be used - just put a comma between each tool.


  <cms:editable type='richtext' label='About Me' name='about_text'toolbar='custom' custom_toolbar='bold, italic, justifyleft, justifycenter' />

Security +

Let's make the CMS more secure, and make it harder for hackers to access.

In the couch folder, rename index.php (going forward, visit the renamed page to login - ie. www.sitename/couch/newname.php)
In couch/config.php, uncomment line 1b and change the name to the new name
In the couch directory, rename _index.php to index.php (this is now a fake login page that won't actually work)

Migrating the Site +

Moving websites from a local computer to actual web hosting is always a bit of a hassle whenever there is a database involved. Fortunately CouchCMS has a handy utility that makes moving the installation easier and more reliable.

Except when working with actual clients, we won't actually be migrating the CMS version of your website to a real host. Keep in mind some of the specifics on the host side might vary due to the host company.

Download the Database:
1. Sign-in to the Couch login page (this must be your Super-Admin User account)
2. In the Couch Dashboard sidebar, click on "Download Dump"
3. In the Downloads directory, find "install-ex.php"
4. Copy or move "install-ex.php" into the couch folder for your website
Hosting Steps:
1. In the host's control panel/site tools, find and open the MySQL Manager
2. In the Users tab, create a new user — make sure to save the username/password in your site documentation for later access (you may or may not be able to choose the username/password depending on the host)
3. In the Databases tab, create a database (if you have the option to name the databse, use the same name that was used for the local site)
4. Make sure the user you created is assigned to the new database with full permissions
Update couch config:
1. Open couch's config.php file again and update with the new database information:
  1. database_name - 'new_database_name' (assuming the databse name changed)
  2. database_username - 'new_username' (previously 'root')
  3. database_password - 'new_password' (previously '')
  4. Save changes
Complete migration:
1. Upload the entire site to the new host — this could be using FTP, the host's File Manager, the host's Site Migration Assist (if applicable) or etc.
2. In the browser, go to your site's couch folder — ie. https://www.your-site-domain.com/couch/ (or whatever the url is for your hosted site)
3. Couch will prompt for your admin login and then run the installation in the new location

Additional CMS functionality can be added by following the Couch CMS documentation & tutorials and by searching the user forum.