Butterfly, a digital agency in Melbourne have been building Joomla websites for 10 years, and are one of the largest agencies in Australia who use Joomla. Development Team Leader Dylan McTaggart will be sharing some details about how Butterfly use Joomla to provide solutions to their clients.
He will be sharing interesting learnings and knowledge from the team's collective experience such as how they use a "skeleton" Joomla install full of extensions and libraries to get up and running quicker, how team collaboration on projects is increased using a front-end SASS framework in Joomla, and much more.
6. What is a “Standard Install”?
“Skeleton” Joomla code.
Based on latest stable package
release.
More than just a base template.
Lightweight – only shared code allowed.
7. Butterfly Standard Install features
HTML5 base template.
Base styles and assets.
Common 3rd party components.
Baked-in WCAG standards.
10. Why use a Standard Install?
Centralised base code.
Time saving – implement once,
continuously reuse.
Maintenance time is reduced.
11. Follow a good SASS structure
and naming convention
Tip 2
12. Why follow a structure?
No structure = messy code.
No need to reimplement the same code over and over.
Developers all do things differently.
Standardise development processes.
13. Good vs. bad
It’s relative to the project.
No structure – all in one big CSS file: Bad
Changing structure from project to project: Bad
Flexible & extensible structure: Good
14. We made our own framework
Based on inuitcss SASS framework1.
We don’t use bootstrap – wanted more control.
Following BEM naming convention.
Compiled with GULP.
1 https://github.com/inuitcss/inuitcss for reference
15. css/
├── settings
├── tools
├── generic
├── base
├── objects
├── blocks
├── pages
└── trumps
The structure
Settings
Variables initialisations (eg. colours, base
font sizes and layout defaults).
Tools
Mixins and other functions (E.g. breakpoint
calculation mixin, font CSS mixin).
16. css/
├── settings
├── tools
├── generic
├── base
├── objects
├── blocks
├── pages
└── trumps
The structure
Generic & Base
High level styles. Site foundation styling
and HTML cross-browsers resets.
Objects
Grouped styles for reusable elements.
Blocks
Styles for standard code blocks and
extensions.
17. css/
├── settings
├── tools
├── generic
├── base
├── objects
├── blocks
├── pages
└── trumps
The structure
Pages
Custom styles for particular pages (E.g. home
page, search page, contact page).
Trumps
Utility and helper CSS styles.
18.
19.
20. How to choose what to use?
Find a structure that:
– Suits your team.
– Suits your projects.
Make sure you can extend when needed.
If no good options – make your own!
22. Why a library?
Share across all extensions.
Joomla framework lends itself
to making libraries.
Promotes code reusability.
Code maintenance is easier.
23. Example: BFToolkit
Recent project requirements:
– Simple event management.
– Custom searching functionality.
The solution:
– A new custom events component.
– Our custom search component.
24. Example: BFToolkit cont.
Custom date range field built for events.
High potential for reuse.
Components refactored to use library.
Moved the field class to “BFToolkit” library.
25. Outcomes of using a library
Independent extension usage.
No bloat within either component,
only use what is needed.
Better user experience.
Maintenance time is faster.
26. Examples from BFToolkit
Custom fields
Date range field, used within our custom
components as a filter.
Helper classes
Extended Joomla Tags helper.
Base API Client
Generic REST API client. Wrapper for
CURL methods, retrieving data and
logging.
27. When to make a library?
Using same code multiple times. Yes
Potential for reuse. Yes
Use code without needing entire component. Yes
Extension context is required. No
29. Forward thinking helps
Follow a good solution design.
Understanding requirements is key.
I ask myself:
– Can we reuse this in future?
– How can I build this to be extensible/flexible in future?
– What is not going to be reusable?
30. E.g. Butterfly API Component
The problem
Salesforce and Joomla integration.
Map data from Salesforce to Joomla Articles.
Preferably real time.
+
31. E.g. Butterfly API Component
The solution
Custom REST API component.
API endpoints configurable
through Joomla backend.
Configurable data parameters.
33. E.g. Butterfly API Component
The future thinking
Created base resource class.
Developers can create subclasses
as needed.
Reusable for other 3rd party
integrations.
34. Don’t keep reinventing the wheel
Shared team mindset.
Reusable solutions = time saver.
Easier for team to learn.
Perfect, rather than reinvent.
36. My experience at Butterfly
Intern 4.5 years ago.
Not many development processes.
Ad-hoc development cycles, every project fixed price (Waterfall).
37. My experience at Butterfly cont.
Moved to Support/Small projects team.
Increased client knowledge.
Learnt to build small extensions efficiently.
Understanding of issues that commonly arise.
38. My experience at Butterflycont.
Moved to Development team when
graduated.
Learnt to build larger extensions.
Worked on larger projects.
Shared my learnings to my new team.
Development processes created.
41. The outcomes of collaboration
Good processes = greater team
understandability.
Best practice actively encouraged.
Improvements shared more regularly.
Reduction in development support
queries.
42. Tips Summary
Butterfly’s top tips
Having a Standard Install improves project start up time
Follow a good SASS structure and naming convention
Reusing utility classes? Make a library
Build extensions with future implementations in mind
Good development processes = better team collaboration & code quality
Hello and welcome everyone!
My name is Dylan McTaggart from the digital agency Butterfly, and today I will be sharing some of what we have learnt working with Joomla.
Firstly, a bit about myself:
I’ve a Bachelor in Software Engineering from RMIT university
I am a Development Team Leader of 11 developers at Butterfly, as well as senior developer on our larger projects.
I have been with the company for four and a half years now, starting off as an intern while studying at uni.
Due to this, I’ve really been able to witness first-hand, and even contribute to, some of the learnings mentioned within this presentation.
Just a quick overview of where I work:
Butterfly is a digital agency centralised in the Melbourne CBD, with clients from all around Australia.
In total, we’ve been working with Joomla for 10 years, building on and extending since the earliest versions of Joomla itself.
Over the last couple years, we’ve adopted the Agile methodology SCRUM and have been applying it to our projects.
All of our team are in-house, allowing us to collaborate a lot easier and helped with introducing SCRUM.
A couple of notable recognitions:
BRW Fast 100 2012 & 2016
APAC CIO Outlook magazine - top 25 most promising agile solution providers of 2017
joomla.org.au site
So, as mentioned earlier, my topic for today is “Top tips about what Butterfly have learnt from our 10 years of experience.”
The reason we decided to present on this comes back to us having celebrated the company’s 10 year anniversary a few months ago.
Having seen how far everything has come over the years, it was realised that collectively we have learnt so much in our time working with Joomla.
We’ve gone from being a tiny business to one of Australia’s largest Joomla companies, and felt it right to give back to the community that has helped to get us to where we are today.
So I have compiled a list of top 5 tips that will hopefully help individuals getting started with Joomla development, companies who are thinking of developing for Joomla, or even those who have been using it for just as long as us.
Lets get started with..
Tip 1:
A Standard Install improves project start up time
Your first question is probably “What even IS a Standard Install”?
Well, the way we define our Joomla Standard Install:
It is basically the same as the most stable package release of Joomla, but with extra additions to allow developers to start projects not from scratch, but rather with base “skeleton code” to get up and running a lot faster.
It’s not just a custom base template – it is an entire Joomla install with either custom or third party extensions included. Typically anything that is continuously being used on projects in the same way will be implemented.
Additionally, it should be lightweight – so it should not contain anything that is not going to be used within all or most projects. For example: project-specific styles should not be in a standard install.
Some of our standard install features:
HTML5 base template, allowing us to utilise modern web features
Base assets and styles, such as:
Heading styles
Base HTML element styles
Form element styles
A number of 3rd party extensions we commonly use across projects such as:
RSFirewall
RSForms
JCE Editor
We have also included basic WCAG compliance for certain areas such as:
Keyboard navigation
Form accessibility
We’ve also added in a number of our own bits and bobs, such as:
Our own SASS framework in the template, of which I will talk about more shortly
Custom extensions that we can reuse across multiple projects. For example: A plugin that allows modules to be assigned to component views as well as positions, for even more flexibility with layouts.
Template overrides for standardising our layouts
And a basic contact & search form set up and styled
Here is an example from the “Standard internal” page from our standard install
Basic heading and copy styling
Menu styles
Base layout setup
Up top left, “Desktop” is one of our SASS trumps for debugging which media query is currently active
But, why use a standard install?
By having all your base code in one central place, you can significantly reduce project start up time.
Developers don’t have to continuously reimplement something that they have been doing the same for years.
As an example: when something is recognised as reusable across projects, we will discuss if it is worthy of our Standard Install, and implement if so, saving us time in future having to implement it again.
You can assure that any fixes can be easily applied to all future projects.
Tip 2:
Follow a good SASS structure and naming convention
Why should you follow a good SASS structure? And what classifies as “good” over “bad”?
Well, to firstly address the why:
Without a structure, template styles can become very messy and difficult to maintain.
Easier to reuse code and styles across projects, as well as extend as needed.
Developers all do things differently. Everyone has different experiences and backgrounds, everyone learnt how to code differently and will think their way is best.
So by introducing a framework, you standardised your development processes and made it easier for anyone to pick up a project.
As for good and bad structures - this is all relative. However, from what we’ve learnt:
All CSS in one big file un-minified, not utilising any CSS extension languages: BAD.
A SASS structure that majorly changes from project to project: BAD
A SASS structure that is built with flexibility and extensibility in mind, providing developers the ability to add their own styles in the same way every time: GOOD
With all that in mind, when it came to us implementing a framework, we decided to make our own.
It is based on the inuitcss SASS framework
We wanted more control than what bootstrap offered, so decided against using it. Mainly we didn’t always want to be locked into the bootstrap structure and methods for extending.
Following BEM (Block, Element, Modifier) naming convention, to help standardise how backend and frontend developers create element classes.
And we use GULP to compile and minify to CSS
This is the directory structure of our framework.
To go into detail about what each directory contains:
Settings
Variables initialisations (eg. colours, base font sizes and layout defaults)
Tools
Mixins and other functions (E.g. breakpoint calculation mixin, font CSS mixin)
Generic & Base
High level CSS styles. Within here will be site foundation CSS and HTML cross-browsers styles.
Objects
Thinking of HTML elements in the same sense as object-oriented objects: they have one role and one set style. An example of these objects styles within this directory are button styles.
Blocks
Styles for standard code blocks and extensions (E.g. Header and footer blocks).
Pages
Custom styles for particular pages (E.g. home page, search page, contact page).
Trumps
Utility/helper CSS classes and styles (E.G. clearfix CSS, our code to help debug responsive styling). These should be able to be used anywhere, and override anything.
As well as this, we also have a base style.scss file which imports everything from these directories, and is what GULP uses to compile to CSS.
Here is an example of the style.scss file from a project. You can see how we have also broken this file up into different sections, however not just for clarity.
This is also because the framework adheres to an inheritance hierarchy, which when compiled to CSS follows the top-down inheritance built into the CSS language.
This reverse pyramid diagram helps to demonstrate better how this inheritance works.
The files at the top in settings, tools and generic are more broad. They are the highest level and set up your foundation.
Moving further down into base and objects, these start overriding your foundation styles and are becoming more specific.
Moving into components (in our framework we’ve broken this section into “blocks” and “pages”), your styles are becoming even more specific to certain pages/areas of the page.
Finally arriving at trumps, which do just that: trump all other styles when needed, as they are the lowest level and are included last.
I’ll finish this tip on a couple of ways to choose a SASS structure that will work for you.
Make sure that, whatever you do end up using, it works for you. Whether you are a team of one or a team of ten, you all need to be across how the structure works, and how to code within it.
Make sure it’s not more work than what your projects need. If you are following simple designs, maybe an even more lightweight structure than ours will work for you.
Make sure you can extend it when needed. You don’t want to be having to completely change it every time you need to introduce something new.
And finally, if you really cannot find any options that work for you, follow our lead and build your own!
Tip 3:
Reusing utility classes? Make a library!
Why a library?
Allows for sharing utility and helper classes and code across all the work we do.
Joomla’s namespace registration method (using JLoader) lends itself to creating libraries
Allows for autoloading our classes when needed
Makes us follow a naming standard that is compatible with Joomla’s loading framework
Promotes code reusability, meaning you can implement once and be assured that it will work the same way across everything.
Same for applying a patch for maintenance. As extensions will pull code from the same place, you can be assured that the fix will be reflected throughout.
To better demonstrate why to use a library, here is an example from one of our recent projects.
A recent project had two requirements:
Simple event creation and management on the site
Custom searching functionality (not only for events, but all content on the site)
Our solution for these requirements were:
To create a new custom events component
And to use our existing custom search component (built using Sphinx search)
We built a date range field for the events component for simple filtering, but quickly realised we could also use this within the search component, as well as other potential components.
Instead of duplicating the field class and adding to the search component, we refactored both components to use our custom library “BFToolkit” we have in our Standard Install.
We then moved the field class to the library, and had each component import from here.
Some of the outcomes of implementing the library in this way are:
Both extensions can be used independently still, only including the field if required on a project. This ensures that both components can remain lightweight, but still highly customisable when required.
We standardise the field, making it work the same across both components. This helps to have good UX within the site.
And by reusing the same code, if we need to fix a bug or add a feature we can be sure it is reflected across all extensions at the same time, rather than having to fix each one.
Here are a couple other examples of what we have included within BFToolkit
Custom fields such as the date range field mentioned before.
Helper classes, such as an extended Joomla tag helper. We do quite a lot of work utilising the tag manager, and required more flexibility with how we use tags within extensions.
And a base API client, which is just a generic class that has wrappers for the relevant CURL methods needed to make REST API calls.
I’ll finish up here with some tips as to when you should make a library, and when you shouldn’t.
If you find you are reusing the same code many times, across multiple different extensions, then yes.
If you think that the class or helper you’ve created could be used again in future, yes.
You want to be able to use classes such as field without needing to install and include an entire component, then yes.
However, if your class requires a custom extension to work correctly, then there is no real benefit.
Tip 4:
Build extensions with future implementations in mind
While this seems good in theory, it can often be difficult to implement in practice without a properly though out solution design.
Really understanding what is required for the project can also help with making good design decisions.
Something flagged as not necessary now may become relevant in future, so it is better to at least consider it when implementing your solution.
I ask myself the following while on a project:
Can we reuse this in future?
How can I build this to be extensible/flexible in future?
What is not going to be reusable?
Asking these questions, if anything, gets me in the right mindset from the start, and allows me to properly consider other better implementations, rather than just the one that gets the job done fastest.
Here’s an example where we built a component with future implementations in mind.
The problem
For a project, we needed to integrate with Salesforce to allow the client to push content down to Joomla.
Data would need to be mapped to Joomla content for easy viewing and modification.
Preferably real time, not polling for changes.
The solution
We built a REST API component that dynamically created endpoints for Salesforce to push data to.
The API end point resources and CRUD methods are all configurable within the administrator section of the component.
As well as this, you can set up the data expected by each end point for mapping Salesforce events data to Joomla articles.
Here is also an example of how you can configure dynamically the different parameters accepted by the end point. You can see it is utilising the subform field introduced in Joomla 3.6.
The future thinking
We built a base resource class that can be extended and assures that the correct REST methods are implemented.
Using the base class, we allowed for a developer to create different resource classes as needed, not just the one we originally did for events.
This component can now be reused to allow for other 3rd party applications to push to Joomla without major code rework.
With your team sharing this mindset, you don’t need to keep reinventing the wheel.
You save time by delivering reusable solutions that can be modified to work for other projects.
By building extensions that are reusable, your whole team can become familiar with them.
As well as this, your team will also be able to improve upon and perfect what already exists.
Tip 5:
Good development process = better team collaboration & code
To best demonstrate why good development processes are important, I’m going to share with you all a bit about my experience at Butterfly.
As mentioned earlier, I started as an intern 4.5 years ago doing front end work only, while still studying at university.
We didn’t have many processes for development at this time.
Development of our extensions was often times ad-hoc and very reliant on senior developers converting old custom built extensions to work with newer projects.
Once my internship finished, and while finishing my degree, I was kept on and moved to the support/small projects team.
In this team, I gained a better understanding of all our sites.
As well as this, I also learnt how to build simple extensions such as modules and plugins in an efficient way, due to small projects typically going for a week at most.
This is where I began to see more similarities in the work we do, as well as understand better where the issues were with reusing code.
When I graduated, I moved to the development team full time, which I have now stayed and moved to a team leader position.
Here I learnt how to build more complex extensions, e.g. components, as well as worked on some of our largest projects.
Utilising my experience in support, I shared to my new team the issues we commonly saw in support with custom work we did, as well as the efficiencies I used while creating smaller extensions.
This created a feedback loop that was missing before.
We all worked together to put in place processes to avoid such issues coming up again, as well as began to share knowledge more within the team to help better our processes.
Just a couple examples of the processes and standards we now follow:
We have these posters around our development area.
They aren’t hard rules, but rather serve as a reminder at to what we all want to work towards as a standard.
Another process that was worked upon and improved once we started to collaborate more was our git structure.
As git is so central to our development & deployment of sites, we needed to ensure that we were following a standard process when working with it.
This process is quite typical for development teams, consisting of feature, staging and master branches.
To finish up, here are some of the high level outcomes of our increased collaboration:
With processes in place, we can now assure that the code we write is understandable and maintainable by anyone within the team.
By encouraging best practice, we also found team members would share their ideas more when they feel something can be improved.
Over time we have seen a reduction in the development-related support queries as a result to improvements in the development team.
So, to summarise all of Butterfly’s top tips:
Having a Standard Install improves project start up time
Follow a good SASS structure and naming convention
If you find yourself reusing utility classes, make a library
Build extensions with future implementations in mind
Good development processes = better team collaboration & code quality
That’s everything from me today!
If anyone has any questions, feel free to come and have a chat with either myself or Rachel, who is also here from Butterfly today, or get in contact via email.
Also check out our website and our Github for some of the resources mentioned in the presentation.