You are here: Home / Blog / posts / Pixelworkers of CAES DO / Git & filesystem magic!

Git & filesystem magic!

by pgang — published Jun 01, 2011 01:40 AM, last modified Jan 28, 2014 02:54 PM
Okay, thanks to one awesome lady, Chrissy Wainwright, I have a new development theme running on our devel server, from git. Let's see how it all went down!

Note: I'll try and contain myself, because I still feel like this is magic and am supes excited that it just WORKS!!! Sure I ran into a few stumbling blocks on the way (see slides 20+), but right now it's amazing: I edit a ploneCustom.css file in a text editor on my Mac, do some git actions, then fire up the page on the development server (not on my Mac)... there be the changes!! <3

Another note: This is largely based off everything I learned from Chrissy Wainwright, über themer from Six Feet Up, and her Plone Theming class last last week at the Penn State Plone Symposium. If you want to start working with this stuff fo' real, I highly recommend learning all the details from her.

git your git in order!

So to preface, we're starting to use github for work as our version control repository. With the theme located on git, both Tyler & I can edit files from our local machines independently.

To start using git, you need to

  1. have it installed on your machine (instructions for FreeBSD == pkg_add -r git)
  2. set up your github account
  3. establish a secure connection between your machine and the github account using SSH keys

Ingredients

Minimum initial structure looks something like: one local machine, one development server, both git enabled; github account with one new repository ready to go (more on this next).

Preparing your theme on server #1

There are a bunch of resources like this one on how to start a new theme on the filesystem, so I'll just start with the basics and you can read more about this elsewhere. Note, Plone themes you're developing should go in the src folder.

Theme From scratch!

On our development server (running Plone 3.3.5 on FreeBSD), in develserver/Plone/zinstance/src I created a new theme using paster by running:

paster create -t plone3_theme awesome.theme

...and then going through the prompts accordingly. (More about each prompt on this guide.) Another note, if you're running Plone 4 and it asks you to enter the skinbase, Plone Default means the classic Plone 3 look (light blue and white) and Sunburst Theme is the new Plone 4 default with the large boxes as navigation.

Next up, Buildout

Now you need to get your instance to recognize your new theme. Do this by referencing the new awesome.theme in your buildout.cfg as follows:

eggs =
   ...
   awesome.theme

zcml =
   ...
   awesome.theme

develop =
   ...
   src/awesome.theme

The ... just mean there are probably other entries there in your buildout as well.

Run buildout, cross your fingers, restart your instance, and with any luck in your ZMI the new theme product will show up!

Moving along to the ZMI...

In your ZMI, create a new Plone site on which to play with this theme. If all went well with the previous buildout step, once you go to portal_quickinstaller, you should see your Awesome Theme in the list of available products! Choose it and click install, and you should be good to go.

Note: if it doesn't show up there... Well... I had that problem for awhile, but I can't say what exactly fixed it. Make sure it looks to be added correctly in your buildout.cfg for starters, and then I tried a round of clearing the cache, killing varnish, restarting varnish, restarting the instance, rerunning buildout, restarting the whole damn server, until it finally just magically worked... Good luck!!

Once it's installed and running correctly, try making a simple change from your file system to ensure that it's working. For example, in src/awesome.theme/awesome/theme/skins/awesome_theme_styles you can create ploneCustom.css and add something like body {background: #FF0000;}. In theory, you should be able to refresh your page and see the change! (Once again, hit a snag here, but make sure your portal_css is in debug mode, and if necessary restart your instance).

Back to git

Excellent! Now to get this onto Github, here's what you do... navigate back into src/awesome.theme for starters.

In your web browser, log back into http://github.com and in the lower right you should see an area for Your Repositories. Click the New Repository button to the right of this. Make the Project Name the same as your theme, i.e. awesome.theme and hit Create.

Github will give you instructions on how to initialize your folder for use with the repository. Follow 'em! I ran into one problem here, but it turned out I had mistyped and set the origin incorrectly the first time, and it wouldn't make any commits after that. If that happens to you, here's a handy guide on removing remotes, and then just run through the original instructions again, but in general you should be fine just copying and pasting the commands out of their guide thing.

Once you're done initializing the folder, add everything into git by doing the following:

git add *
git commit -a
git push

Getting the theme on your local machine

Alrighty then! Now you should have a shiny new theme ready to develop on the development server, and synced to the Github repository you created. In theory, you already have Plone 3.3.5 also running on your local machine. I don't exactly... but that's a whole other matter that I can't deal with right now... The following should work regardless:

On your local machine's file system, navigate to yourmachine/Plone/zinstance/src and create a new folder awesome.theme — once inside, run the following command:

git clone git@github.com:yourUsername/awesome.theme.git

You'll copy the end part (git@github.com:stuff) from, in your browser on your repository page on Github, the box next to where it says Read+Write access. This will pull a copy of the theme onto your machine!

Enter buildout, part deux

Now to get it recognized by the Plone instance on your machine, enter awesome.theme into the buildout.cfg in the same way as above, into eggs, zcml, and develop (src/awesome.theme). Rerun your buildout and do all the fancy restarting that you need to, fire up your Plone instance, and check to see if you can install Awesome Theme on a new Plone site!

End game

If all is successful, then you now have the theme pulled from git running successfully on two Plone instances. Huzzah! In theory how this will work is, we'll no longer have to touch anything directly on the development server. I can make a bunch of changes to my local machine and at various stages, check things into git, log onto the development server, do a git pull and see the changes live there! Here's how this might look:

On the local machine

  1. Edit src/awesome.theme/awesome/theme/skins/ploneCustom.css with something like body {font-size: 10em; color: #00FF00;} /* hulk smash!!! */
  2. In your terminal, in the src/awesome.theme folder
    git commit -a  // it'll open a file, write a comment and then save
    git push

On the Development Server

  1. In your src/awesome.theme folder, do a git pull
  2. Reload your Plone site. Et voila..?!

If that doesn't work, once again check to make sure the cache is cleared, things are properly restarted, portal_css is in debug mode, etc. Hopefully you'll get to the point where that's unnecessary and changes show up just after running through those steps above (make change, commit, push, pull, refresh). Chrissy also showed us a handy add-on, plone.reload, for refreshing your Plone instance's ZCML and code without having to restart the entire instance.

Questions? Better methods? I'd love to hear it! Although our comments are currently disabled... *shakes fist* must install Plone recaptcha soon...

When:

Where:

Contact