Recap of the November Pinax Hangout
The purpose of the Pinax Hangouts is to engage more with the Pinax community. We want to let you know what we are working on, answer your questions, and present demos of old and new apps and starter projects. Our host this month was James Tauber who was supported by our co-hosts Brian Rosner and Patrick Altman.
James, Brian, and Patrick talked about Pinax starter projects and apps.
Pinax Updates: What’s Going On?
We recently hit a 100 members on our Pinax project Slack channel, which is awesome! If you want to find out more about Pinax or chat with us, please join our Pinax Slack channel!
There are more exciting things going on in the Pinax world! Patrick has been working on two major refactors. The first project he’s been working on is symposion, a Django project for conference websites. Patrick has been pulling out some parts of it, starting with pinax-submissions, which is an app for proposing and reviewing submissions. Patrick is not sure yet what the new symposion will look like but stay tuned, it will be awesome!
The second project Patrick has been working on is pinax-stripe, formerly know as django-stripe-payments. It was renamed because of an issue which was conflicting with the namespace “payments”. You may have noticed that we started renaming a lot of our apps with the namespace “pinax” so it seemed appropriate to do the same with pinax-stripe. The app was out of date and behind on a lot of enhancements in Stripe so Patrick has been working on getting the app up to date. He also added ACH payments. The update should be finished sometime this week. We would love for you to check out the new pinax-stripe!
We also stated incorporating our first React component. Pinax has always been Django and Python but lately we’ve been doing more and more with React.
In addition we started pinax-images, an app for managing collections of images associated with a content object, which solves the generic problem of how to handle images and thumbnails in blog posts for example. pinax-images-panel is a React component that we ship which works with pinax-images. You don’t have to use it, it’s just a nice little widget that allows you to upload and select primary images.
Brian has been working on django-user-accounts. He’s been fixing bugs and hopes to do a bug fix release soon. Next Brian will work on new feature development for django-user-accounts. If you have any ideas for new features please let us know in Slack or file an issue on GitHub.
Pinax Starter Projects
James talked about Pinax starter projects and where they fit into the Pinax ecosystem. A lot of people think about Pinax as a project that provides reusable apps, which is true, but an important part of the story around reusable apps in Django are the starter projects. James explained how the idea of starter projects came about, why they are an important part of the Pinax ecosystem, and how apps get developed.
History of Pinax
The idea of the Pinax project started in 2007. A bunch of people in the Django community were interested in reusable apps, which means writing apps and sharing them between different sites. People were also interested in conventions for how apps should be written.
When Pinax started people in the Python world weren’t really using virtualenv and pip. Soon people started noticing the benefits of being able to pull apps from other places, like GitHub later on. pip and virtualenv provided the perfect mechanism for Pinax to draw together apps. Prior to the stabilization of pip and virtualenv the Pinax team put a lot of things just into the Pinax repository. For a long time there was just one Pinax repository. It contained things like the scaffolding app to start with and starter apps that hadn’t yet been broken out. The Pinax team later realized that there wasn’t just one starter project which was appropriate scaffolding for everything so we started to develop other projects, which all lived in the same repo in different directories. This lead to the notion that you could download Pinax, which is no longer true. Pinax is an ecosystem of a lot of different apps and starter projects now.
You can find out more about the history of Pinax here.
Why Starter Projects Are Important
When you’re developing apps for Django you want to have some kind of project to scaffold, which is one of the roles that Pinax starter projects play. Apps can’t be written in isolation. You can’t develop an app on its own. It has to run in a project. If you want to develop a new app, you need to have a project to put your app in. Apps are always part of a project, part of a website. Websites provide scaffolding for apps from the very beginning.
Reusability isn’t always just at the level of an individual app. Often what’s reusable is a collection of apps wired together in a particular way. If you’re thinking of things just as separate apps, you’re missing out on help on how to integrate different components together. The Pinax philosophy has always been that we want to avoid apps that do the whole thing. Instead we want to adopt the idea of each app doing one thing and doing it well. If you think of a blogging app for example, a blogging app might have comments and tagging. In Pinax we don’t try to have a blogging app that has tagging and comments already included. We try to do a blogging app and have separate comments and tagging apps, which you can all put together. Usually apps can be grouped into certain categories and go well together. The starter projects can out-of-the-box show how multiple applications can integrate together.
Another thing we learned over time is that people are much more motivated to build a site than a library or an app. One of the roles of starter projects it to motivate the development of apps by coming together to build a site. That’s why in 2008 we started building a social networking site, which was the sort of framework that showed us which new apps we could build. For example, we needed a way to do announcements for our social networking website so Brian wrote django-announcements. The real motivation for writing these individual apps came about because we had a site that we were building. In the early days this lead to confusion that Pinax was a social networking site so we decided to rename the site which later became Cloud27.
An important idea in software development is that it’s much better to start concrete and then go abstract. It’s much better to build a site that has functionality and then to break up the various pieces rather than building an app in isolation when you’re not really putting it to use.
A fourth reason why starter projects are important to the Pinax eco system is that templates best live outside individual apps. Both for consistency and because web pages often integrate information from multiple apps, it generally makes sense for page level templates to live outside of apps whether they’re in a theme or they live in a project.
So to sum up the four reasons why starter projects are a really important part of the Pinax ecosystem:
- They provide scaffolding for developing apps. Apps can’t be developed in isolation.
- Reusability isn’t just at the reusable app level. Starter projects provide a way of demonstrating and testing how apps work together.
- It is much more motivating to work on an actual running site than to work on a library or app. It’s better to go concrete first and then abstract.
- They provide a way of developing templates that bring together multiple functionality.
Different Types of Starter Projects
There are three different types of Pinax starter projects.
The first type of projects serves as scaffolding or a starting point of a project. When you want to build a site and you know it will need user accounts enabling people to sign up and providing password management and settings management, something like pinax-project-account would be a good starting point for you. You could then either write your own apps or use other apps in the Pinax ecosystem to extend your project. The idea of these foundational projects is that they are your starting point of your project. You are then expected to add things, customize things, etc.
The second type of starter project is the demo project. These types of projects are not designed to be the starting point for your own site or something you would install and run out-of-the-box. They are designed to be a demo for how to put certain apps together or for how certain apps work. Demo projects are a good way of motivating the development of new apps. If you have an existing app that you want to be part of the Pinax ecosystem or you have an idea for an app, a really great way to bring it into the ecosystem, would be to create a demo of that app or collection of apps working together.
The third type of starter project is the out-of-the-box type project. This is not just a demo but something you could deploy the way it is. It might need a bit of customization but it is otherwise fully functional and ready to go. Besides a few simple customizations it is not expected that you would do much coding for these kind of projects. They are meant to be used out-of-the-box.
Hierarchy and Organization of Pinax Starter Projects
In the early days of Pinax we had one repository and our starter projects sat in different directories, which was not a great way of organizing them. We then moved forward to having a separate repository for every single project. The problem with that was that there is a natural hierarchy to all Pinax starter projects. We for example have pinax-project-zero, which is the bare minimum standard layout that we recommend for Pinax projects. pinax-project-account builds on pinax-project-zero and adds basic account management with django-user-accounts and a couple of other apps. We then have other starter projects which build further on pinax-project-account. Having completely separate repositories for all these projects was a maintenance nightmare. After discussing how we could better manage the relationship between those starter projects and taking into account the fact that there was sort of a family tree of these things, we realized that we could better take advantage of git by treating different starter projects as different branches of the same repository.
There’s now a repository called pinax-starter-projects, which on master doesn’t have much other than a README but it has a branch for pinax-project-zero, pinax-project-account, etc. So if for example something gets updated in pinax-project-zero our new way of organizing starter projects makes it really easy to merge it back into the downstream projects.
Adding Apps to Starter Projects
One question that often comes up is how you go about adding new apps to starter projects. A typical pattern when adding Django app to a Django project is the following: You add the app to your requirements.txt file because you are bringing an external app into your project, you then pip install the requirements.txt file (pip install -r requirements.txt), you modify urls.py and settings.py and potentially make template and style changes. There is nothing special about Pinax apps and the way they are added to a project. Pinax apps are just Django apps. You add Pinax apps the way you would add any Django app to your project. You can also add any Django app to a Pinax project.
James thought the easiest way to show how apps are added to Pinax starter projects would be to do a diff between different projects and to show what was added to go from one to the next project.
The first diff James showed was what was added to pinax-project-zero to turn it into pinax-project-account.
pinax-project-account provides basic account management that you get on any site that has user accounts. The core functionality of pinax-project-account consists of the app called django-user-accounts. The project also contains metron, which is an analytics and metrics integration app for Django, and pinax-eventlog, which is an event logger, which means you can go back and see what users were doing on your site. That means we are adding 3 separate apps to pinax-project-zero, plus a Django JSONField which pinax-eventlog needs. By adding our apps to requirements.txt and then installing the requirements file we are bringing these new Python packages into the virtualenv and making them available.
Next we are adding our three apps to our INSTALLED_APPS in settings.py. In this particular case we also add the admin since it’s not turned on by default in pinax-project-zero. Additionally we add a context processor which is provided by django-user-accounts. We’re also adding the account urls under account/. pinax-project-account adds the admin, which pinax-project-zero doesn’t have so we also have to add static media serving.
Sometimes when adding a new app it will require you to set up some additional settings. In the case of django-user-accounts you can customize certain settings. Please see our previous Hangout on django-user-accounts for more information.
There are additional things which occasionally come up. In this particular case we’re adding some receivers and log them using pinax-eventlog. The receivers have to be hooked up first so we need to make a minor modification to apps.py to import the receivers module.
pinax-project-account out-of-the-box hooks up the various signals that django-user-accounts provides like signup, password changes, etc. If you want anything to be visible to your users you will have to make template changes as well. In the case of adding django-user-accounts you probably want people to log in, sign up, etc. which you need to add to your navigation bar. You should also make changes to the homepage so it has the login and signup buttons.
There’s another change we have to make because of metron. Installing metron, as well as putting it into requirements.txt and INSTALLED_APPS also involves making minor modifications to site_base, adding an analytics tag and a load_metron tag. Additionally we made a style change and added an account.less file and hooked it up.
If you would just start out with pinax-project-account you wouldn’t have to take these extra steps we took because django-user-accounts, metron, and pinax-eventlog would already be included in your project.
It’s important to note that you may not notice all the templates for the account views because we are shipping the templates in the theme that was already in place for pinax-project-zero. Templates have lived in the starter projects and they have also lived in the theme. At the moment we are pushing more for app templates to live in the theme. The next example will demonstrate why we want to do that.
Let’s take a look at the diff between pinax-project-account and pinax-project-blog next.
Blog templates live in pinax-project-blog itself, which means there are things you usually have to add and we don’t want people to have to add them, at least by default. pinax-project-blog adds pinax-blog, a blogging app. Like we did in our first diff example, we are adding pinax-blog and other things pinax-blog needs, then hooking up the pinax-blog urls, adding the pinax-blog app to our INSTALLED_APPS in settings.py, adding a context processor to parse through the SITE_NAME and SITE_DOMAIN, and adding a bunch of templates, for example providing editing in the admin, a base template for blog pages, and templates for the list of posts.
If you have an idea on how we can make it easier for people who want to add the pinax-blog to not have to copy these templates over, for example provide them in something like the theme, please let us know in Slack. We’re at least making copying those templates into your project easier, there’s now a management command that ships in the theme that will copy templates down into your project instead of you having to copy them from GitHub. If you want to see how this can be done, please check out last month’s Pinax Hangout on pinax-project-blog.
Please note that pinax-project-blog is actually based on pinax-project-zero, not on pinax-project-account. The reason pinax-project-blog comes off pinax-project-zero is we don’t assume people sign up for your blog, you don’t have user accounts for your blog, etc.
How Can You Contribute?
One of the biggest things we face as app developers is being able to exercise and test our apps. You can write automated tests but you can’t really get a feel for how your templates and views are going to react that way. Starter projects are helpful to test this behavior and to exercise the app.
One way you can contribute to the Pinax project is to start a new project that showcases the use of a particular app or set of apps, or a project that motivates the development of a new app. If you want to develop an app for photo editing for example, a good way to do that would be to develop it in the context of an overall site for sharing photos. It will need other pieces beyond just the photo editing app but the project gives you the scaffolding. You can then collaborate with others and think about what other apps you’ll need, whether they already exist or they need to be written, and so you end up improving the overall ecosystem of reusable apps at the same time as having a project that enables you to test the apps working together and having a demo how these apps work together.
New projects don’t have to be original ideas. You can pick something that has been done a thousand times before but not something that has been done with reusable open source components before. What was successful in the early days of Pinax was picking some existing sites and trying to do a prototype clone built out of reusable apps. This way you have to think of all the different pieces you need for building that site. You are building an actual site but using it to motivate the development and testing of particular apps.
We are always looking for projects that demonstrate how apps work, for testing and demo purposes. Since Patrick has been updating pinax-stripe we currently need a demo project that shows how pinax-stripe works. The best way to show this is to combine a couple of apps, which naturally go together, into a project.
If you have apps that you have written and you’d like to see them be part of the Pinax ecosystem please let us know! They don’t have to live under the Pinax org, they don’t have to live under the Pinax package namespace. It’s just a good way you can get involved in the Pinax community with your existing apps if you build new projects that showcase your app in the context of a Pinax project.
If you have suggestions for other things you’d like to see us talk about in these Hangouts or have feedback of any kind with regard to these Hangouts or anything we’re doing regarding the Pinax project please let us know in Slack!
If you missed our November Pinax Hangout you can watch the video here
If you have any questions, please post them in our Pinax project Slack channel. No matter if beginner, or experienced, we want to help everyone!
Our next Pinax Hangout will take place on Thursday, December 17th at noon Eastern time. The topic will be announced soon. We hope that you will join us for our December Hangout!