[Define New Theme] 4. Reorganize, structure and rename contents within the theme based on standards

General discussion of development ideas and the approaches taken in the 3.x branch of phpBB. The current feature release of phpBB 3 is 3.3/Proteus.
Forum rules
Please do not post support questions regarding installing, updating, or upgrading phpBB 3.3.x. If you need support for phpBB 3.3.x please visit the 3.3.x Support Forum on phpbb.com.

If you have questions regarding writing extensions please post in Extension Writers Discussion to receive proper guidance from our staff and community.
User avatar
hanakin
Front-End Dev Team Lead
Front-End Dev Team Lead
Posts: 968
Joined: Sat Dec 25, 2010 9:02 pm
Contact:

[Define New Theme] 4. Reorganize, structure and rename contents within the theme based on standards

Post by hanakin »

*Note This is part 4 of a series found here

Their are two big topics that I really want to hit on out of all the topics in this series. This is the first of those.

We need to stop re-labeling things to confuse those who maintain and develop the content. We need to adhere to a structure that is more closer if not identical to the industry standards.

Currently we have two folders within the Style directory, Template & Theme. The first confusion should immediately be obvious. This provides confusion as its backwards the overall all directory should be themes and the content within should be a style as the content that we change is a stylesheet

Themes > Prosilver > Template, Style

The next confusing part when first looking a phpbb "Themes" is the breakdown of content it self.

In the Theme directory we have css files and images folder and a language folder? As a designer and developer I have never seen it broken out this way mainly because its confusing! Whats more confusing is that in the Template folder you have HTML and JS files?

We need to take an Asset approach to the breakdown of a theme as this is most common in the design community as well as the development community.

Proposal:

  • themes
    • prosilver
      • assets
        • css
        • fonts
        • js
        • less
        • design <- design related files such as .ai or .psd files
      • includes <- template parts, this is anything that is not a main page & not required for all pages
      • index.html
      • header.html
      • footer.html
      • viewforum.html
      • viewtopic.html
      • faq.html
      • mcp.html
      • memberlist.html
      • posting.html
      • reporting.html
      • search.html
      • ucp.html
      • viewonline.html
This provides a much cleaner easier to work with and maintain structure that has clear division of labor and scope

gains:
- The ability to clearly find exactly what we need to edit
- Immediate understanding of the breakdown of a theme to new individuals to phpbb
- ability to modularize the theme in order to make it more maintainable
- clearly defined and established scope and content

loses:
- Language directory <- but do we still need this I was under the impression that the buttons have all been converted to css?
- The need for more template variables for paths
- Could require some minor changes if not possible complex ones to the template engine

The last aspect of this that I have not hit yet is the changing of the way we breakout the css. I am addressing this separately as if we go down the route of using a preprocessor, then this would be moot as the less files would generate the css.

Currently we are breaking out by property values when it should be broken out based on object relation for modularity and scope.

Thoughts & Suggestions?
Donations welcome via Paypal Image

User avatar
nickvergessen
Former Team Member
Posts: 733
Joined: Sun Oct 07, 2007 11:54 am
Location: Stuttgart, Germany
Contact:

Re: [Define New Theme] 4. Reorganize, structure and rename contents within the theme based on standards

Post by nickvergessen »

hanakin wrote:Language directory <- but do we still need this I was under the impression that the buttons have all been converted to css?
Edit, Quote and the other small buttons are still images.
hanakin wrote:Could require some minor changes if not possible complex ones to the template engine
I don't think it should require this
hanakin wrote:The ability to clearly find exactly what we need to edit
I don't see how this changes. If you edit a css file or image go to theme/ otherwise template/
hanakin wrote:ability to modularize the theme in order to make it more maintainable
What can't be modularized now which could be changed later?

You forgot the most important part: breaking all BC for styles, extensions and custom pages
Member of the Development-TeamNo Support via PM

User avatar
hanakin
Front-End Dev Team Lead
Front-End Dev Team Lead
Posts: 968
Joined: Sat Dec 25, 2010 9:02 pm
Contact:

Re: [Define New Theme] 4. Reorganize, structure and rename contents within the theme based on standards

Post by hanakin »

nickvergessen wrote:
hanakin wrote:The ability to clearly find exactly what we need to edit
I don't see how this changes. If you edit a css file or image go to theme/ otherwise template/
The problem is as I stated its not properly separated out, and breaks established standards. As a developer the first thing I do when I begin a new project is break out my template to start my workflow. I do not want to have a separate template that I have to work from for one piece of software that has its own naming conventions for things that I have to research to determine what they are. A folder structure that provides little in the way of organization. If I am working in a team and we have a designer working on the graphics, A Javascript developer working on the JS and the front-end specialist working on the html/css and integration of all the assets. It is easier to maintain the structure in this context as well. Not to mention swapping in new individuals in those positions who need to familiarize themselves quickly with the project, its easier if its organized in the way that mirrors what they are used to seeing.
nickvergessen wrote: What can't be modularized now which could be changed later?
The modular piece really is more the theme itself I guess. Its just does not appear modular based on the organization.The fact that we have no explicitly defined location for js files however means that some individuals could introduce the JS into the templates based on this construct.
nickvergessen wrote: You forgot the most important part: breaking all BC for styles, extensions and custom pages
[/quote]
Not really since this is for a new theme and not prosilver so thats not really a factor since you would have to update the extensions to work with the new theme anyway. Further more We have made changes in 3.1 that completely change the way the template is organized and setup that would also dictate extensions being updated.
Donations welcome via Paypal Image

User avatar
nickvergessen
Former Team Member
Posts: 733
Joined: Sun Oct 07, 2007 11:54 am
Location: Stuttgart, Germany
Contact:

Re: [Define New Theme] 4. Reorganize, structure and rename contents within the theme based on standards

Post by nickvergessen »

hanakin wrote:The fact that we have no explicitly defined location for js files however means that some individuals could introduce the JS into the templates based on this construct.
Its the template/ folder. you can just try to use INCLUDEJS to include your file and see where it tried to find the file but didnt
Member of the Development-TeamNo Support via PM

User avatar
hanakin
Front-End Dev Team Lead
Front-End Dev Team Lead
Posts: 968
Joined: Sat Dec 25, 2010 9:02 pm
Contact:

Re: [Define New Theme] 4. Reorganize, structure and rename contents within the theme based on standards

Post by hanakin »

You are missing the point. Their is so much clutter in the files that its difficult to see it visually in a folder. This will be ever so much more clutter if everything becomes more modular. I would actually like to break the template files up into block level folders but thats more of a personal preference.

The fact remains division of labor is not clearly defined and it should be. your argument does nothing to point out why division of labor should not be established? If I currently tell you as someone who has never seen phpbb before to make a change to the function for jumping to a page. Where would you look for that? I would first look for an assets folder and a js folder in that. I would then look for a jumpto.js file hmm none of those are available. Now I have to do a search for jump in the whole app to find this one function that I need to edit. Then narrow that down to the definition, A task that should have taken me 1-2 min cause I was only supposed to add a change to the Documentation now takes me 5-10min or longer depending on the individual. This production time adds up.
Donations welcome via Paypal Image

User avatar
DavidIQ
Customisations Team Leader
Customisations Team Leader
Posts: 1903
Joined: Thu Mar 02, 2006 4:29 pm
Location: Earth
Contact:

Re: [Define New Theme] 4. Reorganize, structure and rename contents within the theme based on standards

Post by DavidIQ »

So by modularization you mean break everything out into tiny files, i.e. one per function or feature, and then having them all in separate folders? Sounds messier than what we have now tbh.
Image

User avatar
brunoais
Registered User
Posts: 964
Joined: Fri Dec 18, 2009 3:55 pm

Re: [Define New Theme] 4. Reorganize, structure and rename contents within the theme based on standards

Post by brunoais »

I never locate by file name. I always let notepad++ (or equivalent) do search for it in the .js files.

User avatar
hanakin
Front-End Dev Team Lead
Front-End Dev Team Lead
Posts: 968
Joined: Sat Dec 25, 2010 9:02 pm
Contact:

Re: [Define New Theme] 4. Reorganize, structure and rename contents within the theme based on standards

Post by hanakin »

brunoais wrote:I never locate by file name. I always let notepad++ (or equivalent) do search for it in the .js files.
yes and thats fine for a developer but for a designer or an end user this is almost never the case. And as I mentioned if you are looking for something convoluted then its not easy to search for it. Especially when it comes to template vars
DavidIQ wrote:So by modularization you mean break everything out into tiny files, i.e. one per function or feature, and then having them all in separate folders? Sounds messier than what we have now tbh.
Some what but I am not really proposing modularization in this topic just the folder structure listed. Its actually not as messy as you would think though because the folder structure itself is descriptive.

However on the topic of modularization the css and js should be maintained in two forms production and deployment. deployment files should be minified and compressed. Development should be separate modular files that are well documented These should them be run through something like grunt. Im not proposing that its shipped but maintained this way which I will address again in another topic about separating the theme into its own project!
Donations welcome via Paypal Image

Senky
Extension Customisations
Extension Customisations
Posts: 315
Joined: Thu Jul 16, 2009 4:41 pm

Re: [Define New Theme] 4. Reorganize, structure and rename contents within the theme based on standards

Post by Senky »

hanakin wrote:
  • assets
    • css
    • fonts
    • js
    • less
    • design <- design related files such as .ai or .psd files
  • ...
[/list]
Maybe I would change it a little bit:
  • assets
    • css
      • less
    • fonts
    • js
    • design <- design related files such as .ai or .psd files
  • ...

User avatar
hanakin
Front-End Dev Team Lead
Front-End Dev Team Lead
Posts: 968
Joined: Sat Dec 25, 2010 9:02 pm
Contact:

Re: [Define New Theme] 4. Reorganize, structure and rename contents within the theme based on standards

Post by hanakin »

with the introduction of a style guide/framework we can separate it out completely to its own having only

css
js
fonts
imgs

in the final distribution
Donations welcome via Paypal Image

Post Reply