Hi Folks,

I'm keen to get some feedback on what we can do to improve our documentation.

The Boost Template documentation is online now and perhaps you could use it as a guide for the feedback:

docs.joomlabamboo.com/joomla-template/boost/1_index.html

Do you want more screenshots of settings?
Step by step guidelines?
Better organisation?

Appreciate anything you can provide.

Thanks

Hi Anthony,

Thank you for asking about our suggestions for improving documentation!

Here are my first thoughts about the things I am most interested in seeing. I think most/all of these could be written once as generalized documentation about ZGF4, so it wouldn't need to be duplicated or updated for each template:

• Some background information to explain the structure for section/div/CSS class names used in ZGF4 templates. There are wraps, containers, rows, spotlights, etc. - what is the intended purpose for each, what ZGF4 settings do they map to, etc.? I can usually figure out how/what/where to change things as needed (sometimes with help from you and Paul), but I don't feel like I can really read and understand the underlying code structure for ZGF4 templates, and I would really like to.
• More information about the ZGF4 file structure, including (especially?) the files located under /settings/layouts, and /tpls/blocks, as well as best practices for how/when/where to customize those files.
• Information on best practices for using custom CSS and LESS with ZGF4 templates. Ian (iafdesign) was gracious enough to share some details about the workflows he uses in this forum thread. That was very helpful to me, and I think having a knowledge base with more information along those lines would be a great resource for JB users (along with other ideas/expertise on best practices from the JB team).
• Information on best practices for optimizing page load speed and performance for ZGF4 templates.
• If you are comfortable with it (I would understand if you're hesitant due to potential issues with support, overwriting files on template updates, etc.), I would like to see some documentation on how we could potentially customize the ZGF4 backend admin interface ourselves to add new custom tabs and/or custom fields in existing tabs

Those are the main points I can think of right now. I will keep thinking and add more if I get any other ideas. Thanks for the great tools you are building and the strong support from you, Paul, and the rest of the JB team!

Thanks for this Paul. They all sound great. Ive added them to my list and will get onto it next week once I have the new theme out.
Thanks!

Thanks Anthony! I just asked some ZGF4 LESS newbie questions in another forum thread: http://www.joomlabamboo.com/index.php?option=com_kunena&view=topic&catid=579&id=115121&Itemid=215. I am copy/pasting those questions here - I am not expecting to get answers to my questions here, but I thought they might also be points to consider regarding this topic about overall documentation improvements:

1. Does custom.less work the same as custom.css - do any duplicate classes defined in custom.less override the same classes in other files, or are any classes added in custom.less supposed to be new ones?
2. Are there any rules to keep in mind for the order and manner that newly created .less files get compiled along with the other standard .less files? Mostly I want to know if there are any best practices I should be aware of for creating and importing additional newly created .less files.
   
3. Sometimes after I added a class to custom.less or another newly created .less file I created and called with @import, the LESS wouldn't compile, or it would compile but I wouldn't see the expected change in the frontend. I am sure at least some of that was due to my errors. To get around the LESS compiling problem, I ended up making some changes in the .less files that are packaged in the template. I think that probably was a poor idea. When I install a template update, will any changes I made to existing .less files get overwritten? If so, what would be considered best practices for making .less customizations that won't get overwritten?
4. Are there any best practices guidelines to keep in mind for when a change/customization should be made to a .less file vs a .css file?
   
5. Are there any other newbie ZGF4 LESS best practices to keep in mind?

Thanks,

paul

Update: In the other thread I linked to in my previous post, Paul from JB shared this existing documentation link that helps with some of my LESS questions:
http://docs.joomlabamboo.com/zen-grid-framework-4/theme/customisation.html

Hi Paul,

re your q's:

1. You can override / duplicate any classes in the other files in the custom.css or custom.less file. Thats the safest way to make small changes to existing classes and not have them get overwritten on an update.

2. custom.less files or any files added in the admin get added after all of the theme and framework files so they should take precedence.

3. It may be that the path to the imported file isn't correct. I don't recall exactly but i'm pretty sure its a relative path eg custom.less would import custom-style.less in the same folder like this:
@import "custom-style.less";

4. I think the key would be:

a. Using the less file would mean that you need to recompile in the admin each time you make a change. But it does not result in an extra file being loaded.

b. No need to recompile if using the custom.css file but an extra css file is loaded.

5. Not really - what sort of thing were you trying to do?

Thanks

Ive updated the doc here with some of the answers:
docs.joomlabamboo.com/zen-grid-framework-4/theme/customisation.html

Thanks

Thanks Anthony, your answers are a big help!

Here are a few more questions regarding your last response to my #5 - "Not really - what sort of thing were you trying to do?":

1. If I want to create my own LESS variables and/or mixins, does it matter where I do that so that those variables/mixins could get picked up and applied if referenced inother files? For example if I wanted to define a variable and reference it in a file for a custom row style.
2. Is there a way to reference LESS variables/mixins in custom.css, or should those be thought of as completely separate?

From an overall sense, I think what I am mostly aiming for is to try and get a better understanding of how/when/where I should be making different types of changes/customizations so that I am working with ZGF4 patterns instead of potentially against them (scalpel vs chainsaw). I think I probably just need to dive in and as I get more familiar with LESS, hopefully things will get clearer in my mind.

Thanks again - a lot!

Hi Paul,

1. Less is a cascading language so the variable or mixin needs to be declared before it's used in the code.

So in your custom.less file you would do this:

@import "custom-variables.less";
@import "my-less-file-that-you-can-use-custom-variables-in.less";

But you couldn't add those custom variables to the template files.

So you just need to declare mixins or variables before you use them. You can even just do that in a single file.

eg @blue: red;

#window {border-color:@blue}

2. You should be able to reference template variables within your custom less files eg @twidth.

However it gets a little complicated here because the variables int he template interface override variables set in the templates own variables.less file. So it really depends on which variable you are trying to use.

Re how to edit it's by far easier to edit just with a custom.css file but Less is a much more powerful tool.

I wrote this doc for how to create a copy of the template:

docs.joomlabamboo.com/zen-grid-framework-4/creating_new_themes_with_zgfv4/Create-an-installable-package.html

So what might be a nice place to start is to create your own blank template or starter theme and dive in that way?

Best of luck with it.

Thanks again Anthony, that helps a lot. Now I think I have enough to move forward without feeling like I am stumbling around in the dark. :-D

I think your suggestion to create a blank template and then build on it might just be the best idea of all, as far as really trying to understand the entire framework!

Good luck with it

Cheers
Paul