I've saw a couple users (atually a lot of them) complaining about the hard work of installing a Chevereto update. Indeed is kind of hard and I was expecting to write this in the documentation but since the documentation is still not ready I will write a short guide in how-to customize this and not die trying.
First of all, an explanation on WHY.
Chevereto is separated in several layers of code. We have G\ in the most internal layer, then we have Chevereto core and then the theme system. Chevereto was designed to separate the core from the template so your changes must be at template level or at the controlled instances (routes and chevereto-hook().
If you have notice other systems use template systems or rely in system hooking to add customization layers on their apps. For instance OpenCart has something called VQMod which is a system that rewrites the source code, or you also have the XenForo system which I don't know how is called but is pretty much the same that VB, IPB, Magento, etc. does. The problem with these systems is that they use a lot of memory because each request must interpreter the theme file so they solved this adding cache but that is not the real problem, real problem is how you hook your changes.
For any of those systems you changes must be hooked in custom coding structures and that is a pain in the ass. So in Chevereto we do the same that they do in Wordpress but the difference is that in WP they hook a lot of plugins and the usage is pretty high, a single WP page load could take up to 20 MB memory while a Chevereto call takes only 1.3MB (average).
So if you want to be comfortable customizing (in the way of keep your changes) you will need to learn those coding structures and rely in cache. In Chevereto we don't do that, you only have to follow a method.
Ok, got it what now?
First of all, I recommend to only edit at the layers that are designed to be edited. Those are:
You can still edit any layer you want, is up to you. But keeping the system up to date will be a pain in the ass. So, lets talk about the theme editing.
Theme editing: You are doing it wrong.
Most of you work directly on app/themes/Peafowl and that is the first mistake. You should clone Peafowl into something like "MyTheme" and work in that theme. Don't touch Peafowl default at all if you want to heavy customize your theme (heavy means touch the HTML).
If you want to simply change the logo or customize the style or maybe just add footer or hader code refer to the app/content/themes/<mytheme>/custom_hooks folder.
Theme editing: Why clone Peafowl?
Because Peafowl is the default theme and that theme is always changing. So if you are running 3.1.0 and you want to update to 3.2.0 you will have a lot to think about in the weekend and probably you will be cursing me. By cloning Peafowl thing what happens is that you keep a record in what is going on.
Think in cloning Peafowl like this:
Working like this keeps full or absolute control of the theme, system stability and you don't need to learn one single line of customized "Chevereto template syntax".
Required software
Obviously that you will want to use an automated software to spot the differences between the files. You can also do it manually but is the most inefficient thing in the world. I like a lot Winmerge (http://winmerge.org/) and here is a nice list with alternatives: http://blog.jardalu.com/2012/8/17/top_5_diff_tools
You need to just compare FolderA with FolderB and you will see all what is exactly changes from the moment that you forked Peafowl into "MyTheme" so took those lines and push them back to your theme.
First of all, an explanation on WHY.
Chevereto is separated in several layers of code. We have G\ in the most internal layer, then we have Chevereto core and then the theme system. Chevereto was designed to separate the core from the template so your changes must be at template level or at the controlled instances (routes and chevereto-hook().
If you have notice other systems use template systems or rely in system hooking to add customization layers on their apps. For instance OpenCart has something called VQMod which is a system that rewrites the source code, or you also have the XenForo system which I don't know how is called but is pretty much the same that VB, IPB, Magento, etc. does. The problem with these systems is that they use a lot of memory because each request must interpreter the theme file so they solved this adding cache but that is not the real problem, real problem is how you hook your changes.
For any of those systems you changes must be hooked in custom coding structures and that is a pain in the ass. So in Chevereto we do the same that they do in Wordpress but the difference is that in WP they hook a lot of plugins and the usage is pretty high, a single WP page load could take up to 20 MB memory while a Chevereto call takes only 1.3MB (average).
So if you want to be comfortable customizing (in the way of keep your changes) you will need to learn those coding structures and rely in cache. In Chevereto we don't do that, you only have to follow a method.
Ok, got it what now?
First of all, I recommend to only edit at the layers that are designed to be edited. Those are:
- Routes (overrides)
- Chevereto-hook.php
- Theme
You can still edit any layer you want, is up to you. But keeping the system up to date will be a pain in the ass. So, lets talk about the theme editing.
Theme editing: You are doing it wrong.
Most of you work directly on app/themes/Peafowl and that is the first mistake. You should clone Peafowl into something like "MyTheme" and work in that theme. Don't touch Peafowl default at all if you want to heavy customize your theme (heavy means touch the HTML).
If you want to simply change the logo or customize the style or maybe just add footer or hader code refer to the app/content/themes/<mytheme>/custom_hooks folder.
Theme editing: Why clone Peafowl?
Because Peafowl is the default theme and that theme is always changing. So if you are running 3.1.0 and you want to update to 3.2.0 you will have a lot to think about in the weekend and probably you will be cursing me. By cloning Peafowl thing what happens is that you keep a record in what is going on.
Think in cloning Peafowl like this:
- Clone Peafowl into "MyTheme" (running i.e. 3.1.0)
- Make a lot of changes into "MyTheme" so 3.1.0 stock Peafowl is untouched.
- Download 3.2.0
- Compare 3.1.0 app/themes/Peafowl with 3.2.0 app/themes/Peafowl
Working like this keeps full or absolute control of the theme, system stability and you don't need to learn one single line of customized "Chevereto template syntax".
Required software
Obviously that you will want to use an automated software to spot the differences between the files. You can also do it manually but is the most inefficient thing in the world. I like a lot Winmerge (http://winmerge.org/) and here is a nice list with alternatives: http://blog.jardalu.com/2012/8/17/top_5_diff_tools
You need to just compare FolderA with FolderB and you will see all what is exactly changes from the moment that you forked Peafowl into "MyTheme" so took those lines and push them back to your theme.