Practical tips & tricks for 3.1 style authors

For support and discussion related to templates, themes, and imagesets in phpBB 3.1.
Get Involved
Locked
User avatar
PayBas
Former Team Member
Posts: 930
Joined: Thu May 25, 2006 12:37 am

Practical tips & tricks for 3.1 style authors

Post by PayBas » Wed Aug 27, 2014 1:29 pm

Until we update the knowledge base, I'll use this topic to share some practical tips and tricks for style authors that want to get the most out of phpBB 3.1.

Include template events

With the new extension system, many extensions will start to use template events in order to inject their front-end code into the templates. If you want your style to become popular, you should definitely try to include as much of the "default" template events as possible.

Since prosilver is still the default style for phpBB 3.1, most extensions will be primarily developed for prosilver (and therefore use prosilver's template events). Including these events (in roughly the same location as prosilver) will ensure that future extensions will work with your style.

You can find the full list of template events currently included with prosilver 3.1 in the phpBB 3.1 download package, in root/docs/events.md. You can add your own template events too of course, but unless extensions start using your custom template events, it won't be of much use.


Include {$SCRIPTS}, {$STYLESHEETS} and jQuery

The new extension system lets extensions add custom (external) JavaScript and CSS files. They do this by using the <!-- INCLUDEJS my_script.js --> and <!-- INCLUDECSS ../theme/my_styling.css --> template instructions.

What these snippets do is add the specified files to the list of files that will be loaded in the {$SCRIPTS} and {$STYLESHEETS} template locations respectively. So if you don't include these 2 variables in your templates, many extensions will break (since their front-end functionality relies on these files).

{$STYLESHEETS} should be present near the end of the <head> element (but after <!-- EVENT overall_header_head_append -->).

{$SCRIPTS} should ideally be included near the bottom of the footer (before </body> but after jQuery is loaded).

Also don't forget to include jQuery. It is packaged with phpBB 3.1 by default, and extensions will assume that it is loaded. Make sure the following code is present in your footer (and before {$SCRIPTS}).

Code: Select all

<script src="{T_JQUERY_LINK}"></script>
<!-- IF S_ALLOW_CDN --><script>window.jQuery || document.write(unescape('%3Cscript src="{T_ASSETS_PATH}/javascript/jquery.min.js?assets_version={T_ASSETS_VERSION}" type="text/javascript"%3E%3C/script%3E'));</script><!-- ENDIF -->
Mimic prosilver classes

Since most extensions will be developed primarily for prosilver, they will naturally utilize prosilver's style assets whenever possible. This helps them to significantly reduce the amount of CSS rules that they need to write. If an extension author wants to add a block of rows with content, they could write all the CSS rules themselves, or they could simply rely on the rules already in place. The likely result is that they will recycle prosilver's style rules, with selectors like ul.topiclist.

If you want extensions to work on your custom style with the least amount of effort. Using the same CSS class names on roughly the same elements can help a lot.


Use template inheritance whenever possible

Many styles start off by modifying existing styles (such as prosilver), because creating a completely new style from scratch is an extremely time consuming undertaking. Template inheritance has been part of phpBB 3 for a while now, but is often not utilized in the most efficient way.

With phpBB 3.1, using template inheritance has become much more powerful. This is mainly because of the new template events. Instead of trying to include all these template events in your own style, it's usually much easier to simply inherit them from other styles (like prosilver). This can be a handy time-saver.


Asset "inheritance" (using CSS/images from other styles)

The biggest obstacle for most authors is the fact that the inheritance tree only works for templates, not CSS.

So lets say you want to make a new style, based on prosilver. But you only want to change header, footer, navigation bar, and some images/colors.

You would naturally proceed by creating a new style (with a proper style.cfg, which includes the line: parent = prosilver). Next, you would copy overall_header.html, overall_footer.html and navbar_header.html to your new_style/template directory.

That was the easy part. But how do we inherit prosilver's CSS assets?

There are multiple ways of doing this, and it will depend on whether or not you plan to make really significant changes to the CSS files. I'll try to explain the different ways of "inheriting" style assets, and their pros and cons.

1) Copy-paste all assets (/theme/)
The easiest (and probably most used method) has been to simply copy-paste all the assets (the entire /theme/ directory) of the parent style to the child style's dir, and edit the various .css files to suit your needs.

Pros
  • Easy editing
  • Doesn't require any template tricks
Cons
  • Poor maintainability. When prosilver is updated, and you want to include those updates... you will need to keep track of all your changes, etc.
  • Duplication of assets
2) Relative-path @import with selective replacement
If you only want to make changes to a few of the parent's .css files, you might not want to duplicate all the assets, since that would just clutter your new style. It is possible to only copy a few assets and make changes to them, without having identical copies scattered around the server. In your new style's stylesheet.css, you could include the following code:

Code: Select all

@import url("../../prosilver/theme/common.css");
@import url("../../prosilver/theme/links.css");
@import url("../../prosilver/theme/content.css");
@import url("../../prosilver/theme/buttons.css");
@import url("../../prosilver/theme/cp.css");
@import url("../../prosilver/theme/forms.css");
@import url("colours.css");
@import url("imageset.css");
This would basically load all the parent's (prosilver) CSS assets, except for colours.css and imageset.css, which you want to load from your new style's assets (which you have copied from prosilver, and subsequently edited to suit your needs).

Pros
  • Deduplication of assets
  • Doesn't require any template tricks
Cons
  • Relative path @import rules are bad practice
  • Still requires you to copy all assets that aren't included in stylesheet.css (such as responsive.css, /en/stylesheet.css, etc.)
3) Multiple overriding stylesheets.css in <head>
Instead of copying assets and editing them, you could also write new rules that override the parent style's CSS rules.

Code: Select all

<link href="{ROOT_PATH}styles/prosilver/theme/stylesheet.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet" type="text/css" media="screen, projection" />

<link href="{T_STYLESHEET_LINK}" rel="stylesheet" type="text/css" media="screen, projection" />
What this does is load prosilver's stylesheet.css first (and load all the subsequent components via the @import method as specified in that file). After that, it will load the stylesheet.css of your custom style. You can use @import rules in your own stylesheet.css file as well of course (if you want to split up your code into multiple files), or you could simply put all your CSS rules in the file itself.

Note: using both @import rules and regular CSS rules in the same file is not advised.
Note 2: we use {T_ASSETS_VERSION} as rudimentary form of browser cache control.

This same method can be applied to load other CSS assets directly from the parent (without having to duplicate them), such as responsive.css, print.css, bidi.css, etc. If you wish to use the parent style's language assets, you could use the following snippet:

Code: Select all

<link href="{ROOT_PATH}styles/prosilver/theme/{T_THEME_LANG_NAME}/stylesheet.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet" />
Pros
  • No relative-path @import rules
  • Possible to deduplicate everything
Cons
  • No detailed control over which parts of the parent's stylesheet.css to include/exclude.
4) Detailed overriding link components in <head>
This method works the same way as (3), but instead of including the parent's (prosilver) stylesheet.css, we load the various assets directly (without relying on @import). This allows for greater control of which files to include/exclude.

Code: Select all

<link href="{ROOT_PATH}styles/prosilver/theme/common.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet" />
<link href="{ROOT_PATH}styles/prosilver/theme/links.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet" />
<link href="{ROOT_PATH}styles/prosilver/theme/content.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet" />
<link href="{ROOT_PATH}styles/prosilver/theme/buttons.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet" />
<link href="{ROOT_PATH}styles/prosilver/theme/cp.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet" />
<link href="{ROOT_PATH}styles/prosilver/theme/forms.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet" />

<link href="{T_STYLESHEET_LINK}" rel="stylesheet" />

<link href="{ROOT_PATH}styles/prosilver/theme/{T_THEME_LANG_NAME}/stylesheet.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet" />
Notice that we didn't include colours.css and imageset.css, since we want to use our own custom rules (which we will specify inside our own stylesheet.css) instead of prosilver's.

Pros
  • Complete control over which assets to load
  • No use of CSS @import at all (this is preferable)
  • Possible to deduplicate everything
Cons
  • More complex header template
Which method should I use?
In general, I would say that if your style has relatively minor asset changes, I would use method (3). If your style has more extensive modifications, I would use method (4).


Styling extensions

This is completely optional, but if you feel that the users of your style will likely want to use particular (popular) extensions, you might want to add support for these extensions to your style. This is particularly useful if your style has an unconventional layout, or has significantly modified CSS/image assets.

Many extensions with front-end functionality will include their own stylesheet using <!-- INCLUDECSS my_extension.css --> which will add the referenced file to {$STYLESHEETS} in your <head> (as mentioned above).

Since {$STYLESHEETS} is usually included after <link href="{T_STYLESHEET_LINK}" />, this means that the extension's CSS rules will overrule your style's rules (as intended). You will notice that this gives us a problem. We can't include any specific rules for these extensions in our new style's stylesheet.css, since they will be overruled. We could overcome this by using stronger CSS selectors or adding !important to properties, but this is not a very elegant solution.

Instead, we could simply reverse the load order for our style's extension-specific rules. The easiest way to do this is to move all your style's rules that are specifically for extensions into a new .css file (/theme/extensions.css for instance).

Now we need to include it in the <head> of our template. Note the order.

Code: Select all

{$STYLESHEETS}

<link href="{T_THEME_PATH}/extensions.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet" />
Using this method will ensure that your custom rules are loaded after the extension's own rules, thereby overriding them.


Use automatic template recompiling (during development)

While making changes to template files, it's often handy to be able to see the changes directly, without having to purge your forum cache every time. A neat little trick is to recompile templates automatically after every file change.

Browse to: ACP > General > Server configuration > Load settings and set:
Recompile stale style components: Yes

User avatar
PayBas
Former Team Member
Posts: 930
Joined: Thu May 25, 2006 12:37 am

Re: Practical tips & tricks for 3.1 style authors

Post by PayBas » Wed Aug 27, 2014 3:39 pm

*reserved*

User avatar
Mess
Registered User
Posts: 985
Joined: Wed Jul 01, 2009 6:37 am
Name: Kim

Re: Practical tips & tricks for 3.1 style authors

Post by Mess » Thu Aug 28, 2014 10:33 am

Thanks for the write up. It will come in handy!

User avatar
Raul [ThE KuKa]
Style Customisations
Style Customisations
Posts: 6167
Joined: Mon Dec 08, 2003 9:24 pm
Location: Spain
Name: Raul Arroyo
Contact:

Re: Practical tips & tricks for 3.1 style authors

Post by Raul [ThE KuKa] » Fri Aug 29, 2014 6:18 pm

This great PayBas, we will be very useful. :)

Do I have your permission to translate and share it in phpBB Spain? :oops:
All unsolicited PMs will be ignored.
:warning: Knowledge Base | Documentation | Board rules | phpBB Styles Rules & Policies :warning:


If you like my styles, translations, etc. and want to show some appreciation, then feel free to Donate with Image
:flag_es: phpBB Spain - Online Since 2003 :heart:



User avatar
PayBas
Former Team Member
Posts: 930
Joined: Thu May 25, 2006 12:37 am

Re: Practical tips & tricks for 3.1 style authors

Post by PayBas » Sat Aug 30, 2014 12:57 pm

Raul [ThE KuKa] wrote:Do I have your permission to translate and share it in phpBB Spain? :oops:
Of course ;)

User avatar
PayBas
Former Team Member
Posts: 930
Joined: Thu May 25, 2006 12:37 am

Re: Practical tips & tricks for 3.1 style authors

Post by PayBas » Mon Oct 20, 2014 9:41 am

I'm retiring this topic, in favor of our brand new Styles pages at https://www.phpbb.com/styles/

Locked

Return to “[3.1.x] Styles Support & Discussion”