I’ve been thinking about all the different activities involved so far in the creation of the Grav Course Hub, and I thought I would share them here:



Recently I’ve been exploring online (aka “cloud”) IDE’s for use with my various Grav sites and to also recommend for other educators who use Grav with GitHub (as I do). Yesterday I happily discovered SourceLair, which provides a straightforward online environment to develop and test a variety of Web project types all within your Browser (or in my case on my Chromebook). Other noteworthy highlights about SourceLair include a full-screen Terminal and a public URL which can share with others to view your in-development work.


Continue Reading

I’ve been further refining my sustainable approach of an open design practice for my experience design work in the education field, and (bravely or foolishly) I’ve attempted to craft a working definition of the phrase:




Interested in learning more about open business models? Be sure to check out Made With Creative Commons on Medium.

When mapping out the design of the Grav Course Hub Skeleton, it was important to support the two most popular responsive Web frameworks (Bootstrap and Foundation) so that educators could choose the framework best suited to their multi-device presentation needs.

For folks who decide to use the Course Hub Bootstrap theme, the recently released Gravstrap shortcodes plugin by Giansimon Diblas adds a substantial set of useful Bootstrap framework elements available right in Markdown (no HTML required).

For example, by using the following Markdown when the Gravstrap shortcodes plugin is installed, you can use the Gravstrap Link component to display a Font Awesome icon along with a hyperlink:

[g-link url="http://example.com" menu="Products" icon="cog"][/g-link]

Products link with icon
Figure 1. Products link with icon.

Sometimes it’s important to make a link highly visible to students, so that’s where the Gravstrap Button component can come in handy:

[g-button button_url="http://google.com" button_type="primary" button_label="Click me"][/g-button]

Products link with icon
Figure 2. Hyperlink using the Button component.

The Gravstrap accordion component can be very useful in certain situations, especially in the context of students needing to view a single chunk of content from within a much larger collection.

[g-accordion id=accordion1 name=accordion1]
[g-accordion-item id=accordion_item1 header_id=accordion_header1 title="Open me"]

Anim pariatur cliche **reprehenderit**, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et.

[/g-accordion-item]
[g-accordion-item id=accordion_item2 header_id=accordion_header2 title="Open me too"]

Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et.

[/g-accordion-item]
[/g-accordion]]

Accordion component, with one panel expanded
Figure 3. Accordion component, with one panel expanded.

To learn more about what situations an accordion component is best suited to, I recommend reading the article Accordions Are Not Always the Answer for Complex Content on Desktops.

The above three examples just scratch the surface with what is possible when using the Gravstrap shortcodes plugin along with the Course Hub Bootstrap theme (or any other Grav Bootstrap-based theme for that matter). Explore the full range of available components on Giansimon’s Gravstrap page.

Oh, and if you are wondering why interactive examples were not included on this page, the Grav theme this site uses (HPSTR) is not Bootstrap-based - you win some, you lose some.

In this article, we will look at how to use Grav with GitHub Desktop and Beanstalk (which has automatic FTP deployment built-in) to provide a highly efficient workflow when updating your Grav site, and source control to boot. While GitHub only offers private repositories for paid plans, Beanstalk offers a free plan to store one single repository privately.

You will be required to enter a few commands into your Mac or PC command line interface (CLI) during this the process, so get comfortable and let’s get started.

This article will be substantially updated once the pre-release Git Sync plugin for Grav is officially released (expected in February).

Step-by-step instructions

  1. Download and unzip a Grav Skeleton of your choice.

  2. Download the GitHub Desktop client for your computer (Mac or PC), and once it is installed launch the application. Since you will be using Beanstalk, and not GitHub, you can skip the setup process at this time.

    GitHub Desktop setup welcome
    Figure 1. GitHub Desktop setup welcome.

  3. Once the GitHub Desktop application is installed, you will need to install it’s command line tools. This option can be found in the GitHun Desktop’s ‘Preferences’ dialog on the ‘Advanced Panel’ - look for the ‘Install Command Line Tools’ button and then press it.

    GitHub Desktop preferences dialog with the 'install command line tools button
    Figure 2. GitHub Desktop preferences dialog with the ‘install command line tools button.

  4. Head over to Beanstalk and sign-up for a free account (one user private project plan with 100MB of storage).

    Beanstalk homepage
    Figure 3. Beanstalk homepage.

  5. Once you have signed up and are signed-in, create a new repository by pressing the “Create a Repository” button.

    Beanstalk welcome page
    Figure 4. Beanstalk welcome page.

  6. Next, enter the name of your new repository. Consider the name of the Grav project you will eventually be storing when choosing the name. Once you enter the repository name press the ‘Next Step’ button.

    Beanstalk new repository
    Figure 5. Beanstalk new repository.

    You will next need to make the initial commit to your newly created Beanstalk repository. Launch the command line interface for the Mac OS, which is the ‘Terminal’ app, or if you are on Windows launch the ‘Git Shell’ app which would have been installed along with GitHub Desktop (within the same application folder).

    Mac OS Terminal application
    Figure 6. Mac OS Terminal application.

  7. To streamline the need to navigate directories during this process, I would suggest you place your previously unzipped Grav Skeleton folder to where you wish to eventually maintain it (e.g. in your ‘Documents’ folder). For this operation you will be using the ‘cd’ command, which is for change directory. In your CLI enter ‘cd’, press the space bar, and then drag-and-drop the folder that contains your Grav Skeleton folder (not the actual Grav Skeleton folder) onto the CLI window. With the full path to the folder now after the ‘cd’ command press the ‘Return’ key.

    Mac OS Terminal application with folder dropped after 'cd' command Figure 7. Mac OS Terminal application with folder dropped after ‘cd’ command.

    To make sure you are at the correct directory level, you can use the ‘ls’ command, which is for listing the files stored in a directory. In your CLI, enter ‘ls’ and press the ‘Return’ key. You should see the name of your Grav Skeleton folder in this list (e.g. within your ‘Documents’ folder).

    Mac OS Terminal application with ls command entered
    Figure 8. Mac OS Terminal application with ‘ls’ command entered.

  8. Now you are ready to link your Grav Skeleton folder to your Beanstalk repository by copying the hidden ‘.Git’ folder from the cloned repository to your actual Grav Skeleton folder. Return to your Browser and copy the ‘Git repository URL’ field which should be displayed on the current Beanstalk site page.

    Beanstalk repository, with Git URL
    Figure 9. Beanstalk repository, with Git URL.

  9. Return to your CLI window, and type ‘git clone’, plus a space, and then paste the Git repository URL you have just copied to your clipboard, then a space, and finally the text ‘temp’. This command will clone your Beanstalk repository to your computer within a folder called ‘temp’. Press the ‘Return’ key to run the entered command. You may also be prompted to enter your Beanstalk username and password for this step.

    Mac OS Terminal application git clone command line entered
    Figure 10. Mac OS Terminal application git clone command line entered.

    After a short period of time a message should be displayed about the status of the Git clone command, such as ‘done’.

    Mac OS Terminal application git clone command completed
    Figure 11. Mac OS Terminal application git clone command completed.

  10. We now need to make the Grav Skeleton folder the location of the repository on your computer, rather than the empty temp folder we just created. To do this, we enter ‘mv temp/.git’, plus a space, then the name of your Grav Skeleton folder, plus a space, followed by ‘/.git’. This operation will by copy the hidden ‘.Git’ folder from the cloned repository to your actual Grav Skeleton folder.

    Mac OS Terminal application move folder command entered
    Figure 12. Mac OS Terminal application move folder command entered.

    Mac OS Terminal application move folder command completed
    Figure 13. Mac OS Terminal application move folder command completed.

    Now that you have your Beanstalk Git repository as your Grav Skeleton folder, you can use GitHub Desktop to easily and quickly send any updates back to the repository on Beanstalk with just a click of the button (no more CLI commands are required!).

  11. Return to the GitHub Desktop app, and press the “Add a Repository” button (upper-right plus(+) sign in the main window) in the GitHub Desktop client, then select the “Add” tab within the displayed dialog box, and press the “Choose…” button to select the folder containing your Grav skeleton.

    GitHub Desktop add Repository dialog
    Figure 14. GitHub Desktop add repository dialog.

    GitHub Desktop local Repository added
    Figure 15. GitHub Desktop local repository added.

  12. You are now ready for the first commit to your new GitHub repository. Whenever you make a commit you will need to include a brief text summary - as this is your first commit enter the text “First commit.” into the “Summary” text box (above the “Description” text field), and then press the button “Commit to master”.

    GitHub Desktop first commit
    Figure 16. GitHub Desktop first commit.

  13. Since this is your first commit to your repository, the “Publish” button (upper-left of main window) may need to be also pressed to perform the actual file updates.

  14. With the files for your Grav Skeleton now uploaded to Beanstalk, the final step is to enter the FTP credentials for your automatic deployments in Beanstalk. Return to the Beanstalk site, navigate to your repository page, and press the “Deployments” button.

    Beanstalk Deployments page
    Figure 17. Beanstalk Deployments page.

  15. Press the ‘Create environment & server’ button and then name your environment. Choose ‘Automatic’ deployments (since you will be doing your development work/testing on your local computer and only commit working versions of your site to Beanstalk).

    Beanstalk Create Environment and Server Page
    Figure 18. Beanstalk Create Environment and Server Page.

  16. Choose the type of server you are adding (most likely FTP or SFTP), press “Next Step”, enter in the needed server address and credentials on the following screen, and then press “Next Step” again. You can skip the ‘Optional Settings’ page when it is shown.

    Beanstalk Add Server
    Figure 19. Beanstalk Add Server.

    Beanstalk Add FTP Server
    Figure 20. Beanstalk Add FTP Server.

    Beanstalk server setup complete
    Figure 21. Beanstalk server setup complete.

    Congratulations! You now have a Grav site which you can run and test locally (using MAMP), and with only one click in the GitHub Desktop application have any changed local site files updated in your Beanstalk private repository and have them automatically pushed to your Web server. In my experience, I can make an update to my Grav site and sync changes to Beanstalk for automatic deployment to my Web server in as little as 30 seconds.

    If you are interested in providing a way for other course facilitators and students to collaborate with your Grav site then you should use a GitHub public repository instead of a private Beanstalk one - read the article Using Grav with GitHub Desktop (and Deploy) for step-by-step instructions.

After my first Grav CMS for Educators Workshop it became apparent I should provide a wider range of options for how Web-savvy instructors can install and set up the flat-file CMS Grav, especially when using my ready-to-run Course Hub package.

So, here are four options for installing and maintaining a Grav site:

1) Web Only

Install Grav on a Web server and maintain the site using the Admin Panel, and when needed an FTP text file editor.

While this is the quickest way to get a Grav site up and running, this approach means that all development is performed on a live website (requiring user authentication).

2) Desktop and Web server (one-time deployment)

Develop the Grav site on your desktop using MAMP, and then deploy the entire site folder to a Web server using an FTP app once the site design is complete. Use the Admin Panel to then maintain the site as needed.

Educators can safely develop and refine their Grav site on their own computer, and once ready for the start of term deploy the site using an FTP app. During the term only page editing is done on the live website (requiring user authentication). If you want to periodically deploy your site during development, I recommend using Cyberduck’s FTP app which includes a ‘Synchronize’ feature.

For a step-by-step guide to installing MAMP locally for use with Grav, read the article Running Grav Locally with MAMP.

3) Desktop and Web server (with on-going automatic deployments)

Both of the following approaches use Git. While there are many benefits of using Git when developing a website, the most crucial one is that it provides very fine control over what (and when) changes are pushed to your live website.

Private Git Repository

Install and maintain the Grav site on your desktop with MAMP and then use GitHub Desktop to quickly sync the site to a private Git repository service as needed for later deployment. If you are looking for a free option to start with, Beanstalk offers a one user private project plan with 100MB of storage and includes automatic site deployment to an FTP Web server.

With a single press of a button, an educator can quickly deploy any updates of their local Grav site to a Web server. Any text editor can also be used to directly modify Grav files locally, as well as the Admin Panel with user authentication.

Public (Collaborative) Git Repository

Install and maintain the Grav site on your desktop with MAMP and then use GitHub Desktop to quickly sync the site to a public GitHub repository (free public projects plan) as needed. Updates are automatically deployed to your FTP Web server via a deployment service and ‘edit this page’ links (via GitHub) can be easily included on site pages (provided with several Grav skeleton packages, including Course Hub and RTFM).

The use of a public GitHub repository is my preferred approach, as in addition to quick automatic deployment of site updates all course materials are public and course participants can collaborate on both the content and behavior of the site.

You can view a step-by-step guide to set up Grav with GitHub in the article Using Grav with GitHub Desktop (and Deploy).

If you are comfortable with the command line of Git, you might also want to check out these two super informative articles on the Grav website:

This is a brief guide to help tech-savvy educators ‘flip’ their LMS with the modern flat-file (no database) CMS Grav and my open source Course Hub skeleton package.

Grav Course Hub Screenshot

This guide is now outdated. View the updated Open Course Hub documentation on the new learn.hibbittsdesign.org site.

Table of Contents
Course Hub Overview
Flipping your LMS with Grav
Installing the Course Hub
Working with Grav
Using Git and GitHub Desktop
Setting Up a Course in Grav Course Hub

Course Hub Overview

The Course Hub skeleton is intended to accompany a face-to-face, blended or fully online university course. It supports a flipped-LMS approach using the modern flat-file (no database) Grav CMS as an open and collaborative Web platform.

Course Hub Features

  • A complete ready-to-run Grav package (Source on GitHub)
  • Blog-format, with ‘featured’ (sticky) posts
  • Single course per Hub, multiple courses per Hub or even multiple course sub-sites (blog + multiple pages per course) per Hub
  • Optional important reminders & class preparations areas
  • Hub pages can be easily added/removed/changed
  • Uses Markdown for streamlined cross-platform content
  • Image header area above Hub navigation bar
  • Sidebar is a simple markdown file, which can also contain HTML
  • URL flag to only display page content (for display within LMS). For example, http://demo.hibbittsdesign.org/grav-course-hub-bootstrap/home/week-03/onlydisplaypagecontent:true
  • External links are automatically opened in a new Tab/Window
  • Built-in support for entire Hub to be collaboratively maintained on GitHub or GitLab (for local hosting)
  • Since everything is built with Grav it can be entirely customized

Required Technical Skills

  • Code editor usage (e.g. Atom or Brackets)
  • Markdown or HTML basics
  • Understanding folder hierarchies (i.e. relative links)
  • Webserver access
  • GitHub working knowledge (recommended)

Flipping your LMS with Grav

What is a Flipped LMS?

A flipped LMS approach is where an open platform, in the control of course participants, serves as an alternative front-end to the institutional LMS.

Flipped-LMS approach
Figure 2. Flipped-LMS approach.

Why Flip your LMS?

  • To support pedagogical goals unmet by current LMS/platform
  • To deliver a better student (and facilitator) experience
  • To increase capability of access, sharing and collaboration

Why Use a Modern Flat-file CMS?

As an open source modern flat-file CMS, Grav offers a distinct set of advantages to Web-savvy educators looking to move beyond their institutional LMS:

  • Modern means…
    • Use of current standards (i.e. Markdown, Twig, YAML, etc.)
    • Modular/customizable content chunks (i.e. reuse of content)
    • Further separation of content (i.e. files) from presentation
  • Flat-file means…
    • No database means less (or no) IT involvement needed
    • Content stored in text files rather than in a database
    • In many cases, this translates into faster page access times
    • Increased portability, as moving a site now only requires simply copying files to another location
    • Takes full advantage of the collaborative ecosystem now available (i.e. GitHub, GitLab, etc.)

Want to learn more about flipping your LMS with an open and collaborative platform such as Grav? Explore more visualizations in the article Flipped-LMS Approach Using an Open and Collaborative Web Platform

Installing the Course Hub

Web Only (Quick Install)

Pre-flight Checklist

  1. Confirm Webserver PHP version (PHP 5.5.9 or higher)
  2. Webserver login credentials (username and password)

Installation Steps

  1. Download the ready-to-run Course Hub Skeleton Package (GitHub Repo)
  2. Unzip the package onto your desktop
  3. Copy the entire Grav Course Hub folder to your Webserver
  4. Point your browser to the Webserver folder
  5. Create your site administrator account when prompted
  6. And you’re done! (press the icon in the Admin Panel to preview site)

Desktop and Webserver (Recommended Install)

Pre-flight Checklist

  1. Confirm Webserver PHP version (PHP 5.5.9 or higher)
  2. Download and install MAMP (https://www.mamp.info/)

Desktop Installation Steps

  1. Download the ready-to-run Course Hub Skeleton Package (GitHub Repo)
  2. Unzip the Grav package onto your desktop
  3. Create a folder called ‘MAMP Websites’ in your ‘Documents’ folder
  4. Copy the entire Grav folder into your ‘MAMP Websites’ folder
  5. Launch MAMP
  6. Change the ‘Document Root’ setting on the MAMP preferences ‘Webserver’ tab to the ‘MAMP Websites’ folder (within ‘Documents’)
  7. Press the MAMP ‘Start Servers’ button
  8. Enter ‘localhost:8888’ as the URL in your Web Browser
  9. Choose the displayed Grav folder name
  10. Create your site administrator account when prompted
  11. And you’re done! (press the icon in the Admin Panel to preview site)

If you would like a more detailed step-by-step guide to the above desktop installation process, please see the article Running Grav Locally with MAMP.

Now that you have a Grav site running on your computer you need to sync those site files to your Webserver. My preferred method is to use a public GitHub (Git) repository (to enable contributions by course participants) and an automatic deployment service, as described in the post Using Grav with GitHub Desktop. If you want to keep your source files to yourself, then using a private Beanstalk repository would be a no-cost option as described in the post Using GitHub Desktop and Beanstalk with Grav.

If you are interested in storing your Git repository on your own servers, then the open source tool GitLab could be an option, as described in the post Using GitHub Desktop and GitLab with Grav.

Working with Grav

Now that the Grav Course Hub is up and running you are ready to start working with Grav! To learn how Grav is organized, and how to add and edit pages, read the Grav Basic Tutorial.

You can view the all of the official Grav documentation at learn.grav.org. If you are looking for additional help check out the Getting Help section.

Grav for Educators Workshop Slides

If you are new to Grav, you might find these workshop slides helpful: Moving Beyond the LMS with Grav Slides

Using Git and GitHub Desktop

Setting up a Course

For details about configuring and further customizing the Grav Course Hub read Setting Up a Course in the Grav Course Hub.


Suggestion or corrections to this guide? Edit this Page on GitHub

Here is the list of resources for participants in my Grav CMS for Educators workshops (bit.ly URL is http://bit.ly/1PDs3N8):

Grav Skeletons

Course Hub Documentation

  • Demo (demo.hibbittsdesign.org/grav-course-hub/)
  • ReadMe (github.com/hibbitts-design/grav-skeleton-course-hub/blob/master/README.md)
  • GitHub Repository (github.com/hibbitts-design/grav-skeleton-hub-companion/)

Suggested Desktop Toolset

Installation

Web Install

Pre-flight Checklist

  1. Confirm Web server PHP version (PHP 5.5.9 or higher)
  2. Web server login credentials (username and password)

Installation Steps

  1. Download a Grav Skeleton from this page (see above list)
  2. Unzip the package onto your desktop
  3. Copy the entire Grav folder to your Web server
  4. Point your browser to the Web server folder
  5. Create your site administrator account when prompted
  6. And you’re done! (press the icon in the Admin Panel to preview site)

Desktop Install

Pre-flight Checklist

  1. Confirm Web server PHP version (PHP 5.5.9 or higher)
  2. Download and install MAMP (mamp.info)

Desktop Installation Steps

  1. Download a Grav Skeleton from this page (see above list)
  2. Unzip the Grav package onto your desktop
  3. Copy the entire Grav folder into the ‘htdocs’ folder within your MAMP application folder
  4. Launch MAMP
  5. Press the MAMP ‘Start Servers’ button
  6. Enter ‘localhost:8888’ as the URL in your Web Browser
  7. Choose the displayed Grav folder name
  8. Create your site administrator account when prompted
  9. And you’re done! (press the icon in the Admin Panel to preview site)

Now that you have a Grav site present on your computer you can sync those site files to your server in the future, as described in the post Using Grav with GitHub Desktop (hibbittsdesign.org/blog/posts/2015-12-11-using-grav-with-github).

Markdown Documentation

Grav Documentation (learn.getgrav.org/)

Git and GitHub Desktop Overview

Grav for Educators Workshop Slides