Like any other Grav theme, both of the included Course Hub themes (‘Course Hub Bones’ and ‘Course Hub Bootstrap’) can be visually customized using CSS and/or altering their Twig template files. However, if you make changes directly to the Course Hub theme these will be overwritten when that Course Hub theme is updated. So, what to do?
With Grav being a flat-file (no database) CMS tech-savvy educators have a wider range of possible development and deployment options for their Grav Course Hubs than most other database-driven systems. Recently I’ve been exploring an on-line alternative to my currently preferred local development approach, so I thought I would share both together for easier comparison. Both approaches will let you safely develop and test your Grav site before deploying changes to a live production server.
In this article, we will look at how to use Grav with GitHub Desktop and GitLab. Unlike GitHub, you can install GitLab onto your own server, which is an attractive option for many higher education institutions. A locally hosted version of GitLab is used in this walkthrough.
Speaking of Higher Ed folks, if this process looks out of your comfort zone then likely someone in your local IT services should be able to help you get things going pretty quickly by just following this tutorial themselves.
You will be required to enter a few commands into your Mac or PC command line interface (CLI) during this the process, so warm up those typing fingers and let’s get going.
Download and unzip a Grav Skeleton of your choice.
Download the GitHub Desktop client for your computer (Mac or PC), and once it is installed launch the application. Since you will be using GitLab, and not GitHub, you can skip the setup process at this time.
Figure 1. GitHub Desktop setup welcome.
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.
Figure 2. GitHub Desktop preferences dialog with the ‘install command line tools button.
Using your Web Browser head over to your local GitLab install, sign in and then create a new repository by pressing the “New Project” button.
Figure 3. GitLab welcome message.
Next, enter the name of your new project (repository). Consider the name of the Grav project you will eventually be storing when choosing the name. Once you enter the project name press the ‘Create Project’ button.
Figure 4. GitLab new project.
You will next need to make the initial commit to your newly created GitLab project. 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).
Figure 5. Mac OS Terminal application.
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.
Figure 6. 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).
Figure 7. Mac OS Terminal application with ‘ls’ command entered.
Now you are ready to link your Grav Skeleton folder to your GitLab repository by copying the hidden ‘.Git’ folder from the cloned repository to your actual Grav Skeleton folder. Return to your Browser, scroll down until you see the ‘Create a new repository’ information area, and copy the first line of text in that box (e.g. ‘git clone firstname.lastname@example.org:paulh/grav-skeleton-blog-site.git’).
Figure 8. GitLab project, top of page.
Figure 9. GitLab project, bottom of page.
Return to your CLI window, paste the text you just copied (the first line of text in the ‘Create a new repository’ information area), press the spacebar and then enter the text ‘temp’. This command will clone your GitLab 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 GitLab username and password for this step.
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’.
Figure 11. Mac OS Terminal application git clone command completed.
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.
Figure 12. Mac OS Terminal application move folder command entered.
Figure 13. Mac OS Terminal application move folder command completed.
Now that you have your GitLab Git repository as your Grav Skeleton folder, you can use GitHub Desktop to easily and quickly send any updates back to the repository on GitLab with just a click of the button (no more CLI commands are required!).
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.
Figure 14. GitHub Desktop add repository dialog.
Figure 15. GitHub Desktop local repository added.
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”.
Figure 17. GitHub Desktop first commit.
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. Once complete, refresh your GitLab Project page to see the updated files.
Figure 18. GitLab Project Page with updated files.
Congratulations! You now have a Grav site stored on a GitLab repository.
As a next step you should explore options of how to automatically deploy updated files stored on GitLab to your Grav site Webserver. My current favorite service for this is Deploy and you can learn how to set it up for use with GitLab in the Deploy support article How do I start an Automatic Deployment from Gitlab?.
Alternatively, with a little PHP and server access knowledge you can do this only just using Webhooks (which are supported by GitHub, GitLab, and some other Git repository services) - read the “Automatic Webhook” section within the Grav blog post Grav Development with GitHub - Part 2.
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:
(1/3) Estimated Grav Course Hub 'development' activities (Jan-Mar):— Hibbitts Design (@hibbittsdesign) March 24, 2016
(2/3) Estimated Grav Course Hub 'development' activities (Jan-Mar):— Hibbitts Design (@hibbittsdesign) March 24, 2016
10% Usability assessments#GravEdu
(3/3) Estimated Grav Course Hub 'development' activities (Jan-Mar):— Hibbitts Design (@hibbittsdesign) March 24, 2016
10% Presentation materials
10% Social media sharing/engagement#GravEdu
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.
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:
(1/3) What is a”sustainable open design practice”? My first attempt of a definition is “where the creation of an open product and it's— Hibbitts Design (@hibbittsdesign) March 8, 2016
(2/3) underlying design process is available for all to use and contribute to, and because of the existence of that open product there are— Hibbitts Design (@hibbittsdesign) March 8, 2016
(3/3) potential value propositions for one or more specific groups of the audience for that product”. Thoughts and comments Twitterverse?— Hibbitts Design (@hibbittsdesign) March 8, 2016
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).
[g-link url="http://example.com" menu="Products" icon="cog"][/g-link]
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]
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]]
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.