08: Be Style Conscious

This is a temporary forum setup for the purpose of discussing the EMC standards
Locked
Nuttzy99
Registered User
Posts: 927
Joined: Fri Aug 03, 2001 7:09 am
Contact:

08: Be Style Conscious

Post by Nuttzy99 » Thu Sep 18, 2003 1:41 pm

Be Style Conscious

phpBB has a flexible templating system that has enabled hundreds of additional styles to be created beyond the default subSilver style. However, since it is impossible to account for the differences between all these styles, MODs must be written for default subSilver only. EasyMOD will try to compensate by modifiying other styles when possible, but it is not a perfect system. A convention is needed to provide specifc data on how a MOD should handle individual styles. This section lays out that convention.

The least you need to know:
  • Target template variables for FINDs when possibe
  • Store all modifications for TPLs in style_xxxxxxx.txt that functions like a mini-MOD
  • coversions for new TPL files are stored in the same directory as filename_xxxxx.tpl
[/b]
Community Effort
Similar to the effort for translating MODs, we as a community will have better luck making MODs available for more styles if we all work together. The hope is that this convention will allow all MODs to work on with more styles with less work needed by the Author. Since the data for making the modifications to styles will be stored seperately from the MOD, others can help the Author by independently porting the MOD to other styles and submitting their work to the rest of the community. There are plans to update the http://www.phpbb.com" target="_blank MODs DB to accept these independ submissions (with the Author's approval).


FIND and TPL files
All MODs are written for the default subSilver style. However you must keep in mind that there are hundreds of styles that have been created for phpBB. Our goal is to be as compatiable as possible with maximum number of styles. Note that full compatiblity cannot be guaranteed with any style other than subSilver unless an explict conversion for the style is included with the MOD.

There are a few tips you can follow to better ensure compatiblity. When possible try to key on the template variables (ie {postrow.POSTER_FROM}) as these will be consistent from style to style. While making sure the line is sufficiently unique, strip out as much HTML as possible that could clash with other styles. For example, class assignments and table definitions are likely to change from style to style so avoid including them in your FIND if possible. Lastly, when inserting text into a TPL be mindful that the text may be inserted into non-subSilver styles. Try to keep the text as generic as possible (and if possible) and this will increase the odds of it working with styles other than subSilver.


MODing existing TPL files
If you need to make a modification to an existing phpBB TPL file, the process is very much like dealing with lang_main.php. All the modifications, for all the TPLs to be edited will be stored in style_xxxxxxx.txt that functions like a mini-MOD. For example, say you need to make a modification to templates/subSilver/viewtopic_body.tpl and you want to make a conversion for the blueGray theme. Inside the directory (or any directory underneath) that the MOD is located in, you will need to store a file called style_blueGray.txt. Inside style_blueGray.txt you will include all the MOD Template commands necessary to tailor this style to work with the MOD. You may also include a header so as to describe the file a bit, but EM does not require it. For example you may have something like this...

Code: Select all

############################################################## 
## MOD Title:    Country Flags
## MOD Versions: 1.0.0 to 1.2.0
## Style:        blueGray
## Rev Date:     September 15, 2003
##
## Converter:  Nuttzy99 < nospam@blizzhackers.com > (n/a) http://www.blizzhackers.com" target="_blank
##
############################################################## 

# 
#-----[ OPEN ]------------------------------------------ 
# 
templates/blueGray/viewtopic_body.tpl


#
#-----[ FIND ]------------------------------------------ 
#
{postrow.POSTER_FROM}</span><br />


#
#-----[ IN-LINE FIND ]------------------------------------------ 
#
{postrow.POSTER_FROM}</span><br />


#
#-----[ IN-LINE AFTER, ADD ]------------------------------------------ 
#
{postrow.POSTER_FROM_FLAG}


#
#-----[ SAVE/CLOSE ALL FILES ]------------------------------------------ 
#
# EoM
Note the file to open is in /templates/blueGray and not subSilver. In a sense this is a completely self-containted MOD and everything contained within should be blueGray specific.


MODs that provide new TPL files
Many MODs must provide new TPL files to utilize the MODs functionality. Under the old convention the files intended for subSilver would simply be copied to all template directories. Fundamentally this would work with no problem as the HTML should be fine for all styles. However it is not optimal because classes or other elements of subSilver may not be consistent with other styles.

With the new convention you need only include a file specific to the desired style in the same directory you are locating the TPL for subSilver. For example if you have a foo.tpl for subSilver, simply include a foo_blueGray.tpl and the file will be copied to the appropriate location in the blueGray directory. The _blueGray from the filename will be stripped off while moving to the new location.

Converted files that are not needed will be ignored. Therefore if a viewtopic_fiSilver.tpl also exists in the directory but the fiSilver style is not installed, then the file is ignored. If fiSilver is installed, but a viewtopic_fiSilver.tpl file is not present in the same directory as viewtopic.tpl, then the subSilver viewtopic.tpl will by default be copied to /templates/fiSilver.
SpellingCow.com - Free spell check service for your forums or any web form!
My Other Site

User avatar
-=ET=-
Registered User
Posts: 213
Joined: Mon May 26, 2003 1:35 pm
Location: France

Re: 08: Be Style Conscious

Post by -=ET=- » Fri Sep 19, 2003 1:15 am

Once again, all this looks very good! :mrgreen:
It's nice to see ideas (yours) from previous discussion become reality.

But as always I have some comments... sorry :P

#1 subSilver default style?
Nuttzy99 wrote:However, since it is impossible to account for the differences between all these styles, MODs must be written for default subSilver only. (...) All MODs are written for the default subSilver style.
This is statement of the current situation or an obligation?
http://area51.phpbb.com/phpBB22/viewtop ... 8239#78239

I think it's logical but I though it was not your last opinion...

#2 The specific instructions will be proceed instead of subSilver ones?

Just to clarify this...
Nuttzy99 wrote:If you need to make a modification to an existing phpBB TPL file, the process is very much like dealing with lang_main.php. All the modifications, for all the TPLs to be edited will be stored in style_xxxxxxx.txt that functions like a mini-MOD. For example, say you need to make a modification to templates/subSilver/viewtopic_body.tpl and you want to make a conversion for the blueGray theme. Inside the directory (or any directory underneath) that the MOD is located in, you will need to store a file called style_blueGray.txt. Inside style_blueGray.txt you will include all the MOD Template commands necessary to tailor this style to work with the MOD.
The question could have been asked for the language instruction files too, but these instructions (for style or language), will be proceed instead of the default style (any instruction in "templates/default_style") or language (any instruction in "language/default_language") ones?

#3 What about style localized image?

Same question as for your language instruction files identification. What about style images with text on them? They'll need to be identified as from/for a style and a language.
http://area51.phpbb.com/phpBB22/viewtop ... 9404#79404

#4 And... a suggestion to conclude :wink:

EM is really a very VERY nice MOD to install MODs, but what about if we decide to install a new language and/or a new style after that some MODs have already been installed?

Then, I think it could be very useful to consider the add of 2 functionalities which on one click could re-proceed all style or language instructions of all already installed MODs (one button to fully MOD a new style added, and one to fully MOD a new language added) :)

In another topic you said that you'll ask to keep MOD instructions as is in the admin/mods/ directory after installations, so it's absolutely possible to take them back (the list is in the DB), and proceed them again, ONLY for style or language instructions, no?
This will complete the installation feature of EM I think.

What do you think of that? :D
Eternal newbie

Ptirhiik
Registered User
Posts: 144
Joined: Sun Apr 06, 2003 12:29 pm

Re: 08: Be Style Conscious

Post by Ptirhiik » Fri Sep 19, 2003 3:07 am

hum.. regarding the both language and style articles :

The first though that cames to me was : the mod root dir will be just a mess. Why not explore sub-dirs of the mod main dir in order to call back all mod extensions ? Ok it will require a more intuitive user interface for administration of the mod list, but at least I think this will be necessary to keep a something readable, and so reliable. A folder per mod at display seems to be a good point to start.

User avatar
-=ET=-
Registered User
Posts: 213
Joined: Mon May 26, 2003 1:35 pm
Location: France

Re: 08: Be Style Conscious

Post by -=ET=- » Fri Sep 19, 2003 10:13 am

Ptirhiik wrote:hum.. regarding the both language and style articles :

The first though that cames to me was : the mod root dir will be just a mess. Why not explore sub-dirs of the mod main dir in order to call back all mod extensions ? Ok it will require a more intuitive user interface for administration of the mod list, but at least I think this will be necessary to keep a something readable, and so reliable. A folder per mod at display seems to be a good point to start.
Woahhhhhhhhhhhh 8O
I can't believe what I've just read!

Of course I fully agree with you Ptirhiik :D

Nuttzy already suggest /languages/ or /translations/ folder for language instructions files, and that exactly what I've suggest too with my /lang_mod/ example.
Same for style instructions (my suggest was /style_mod/ but it can be any thing else that's not the problem).
And if you consider that it's will be the mess with all the "xxxxxx_language.php" and "xxxxxx_style.xxx" files (for many style/langues) I fully agree with that and my /phpbb_root/ suggest was an answer (which can solve the lang style image issue too).
http://www.phpbb.com/phpBB/viewtopic.ph ... 597#718597

Don't forget that in some MODs you have MANY files provide with :roll:

Identifying languages and styles files by "_langage" or "_style" is a convention.
It can be done by it's sub-dir location (e.g /phpbb_root/template/subGray/xxxxxx.php). That's just another convention.

But I think that the sub-dir and especially the phpBB structure one has many advantages :)

Just my comments/suggests.
Eternal newbie

Ptirhiik
Registered User
Posts: 144
Joined: Sun Apr 06, 2003 12:29 pm

Re: 08: Be Style Conscious

Post by Ptirhiik » Fri Sep 19, 2003 11:15 am

The point is there is no need to qualify the dirs actually : as a mod description is present for each part, each one can be easely identify and named, so installed. Regarding qualifying the filenames, well, I think it is only a paliative to the need to be able or not to apply a mod to what it isn't done for, so to provide a choice to the guy installing mods. The solution choosen can not allow to manage style as family of (ie: subSilver family, fi family, etc.) where select options will perfectly do the work.

User avatar
-=ET=-
Registered User
Posts: 213
Joined: Mon May 26, 2003 1:35 pm
Location: France

Re: 08: Be Style Conscious

Post by -=ET=- » Fri Sep 19, 2003 12:04 pm

Ptirhiik wrote:The solution choosen can not allow to manage style as family of (ie: subSilver family, fi family, etc.) where select options will perfectly do the work.
I agree with you Ptirhiik, but what you ask (with which I fully agree) is a new EM feature that can be add but which does not replace EMC conventions to manage styles/languages files identification.

But one more comment about my suggest and the EMC conventions.
There is another convention, "the kind of command to manage these files in the MOD" that can be discuss (and this post is only here to explain the possible choices and the consequences - not to ask or suggest anything!).

Taking in consideration your (Ptirhiik) manual installations concern...
Here is an example of phpbb_root structure...

Code: Select all

/phpbb_root/language/lang_english/lang_mod.php
/phpbb_root/language/lang_french/lang_mod.php
/phpbb_root/templates/subSilver/overall_header.tpl
/phpbb_root/templates/subSilver/images/lang_english/new_button.gif 
/phpbb_root/templates/subSilver/images/lang_french/new_button.gif 
/phpbb_root/templates/subGray/overall_header.tpl
/phpbb_root/templates/subGray/images/lang_english/new_button.gif 
/phpbb_root/templates/subGray/images/lang_french/new_button.gif
I previously suggest that this structure may allow "copy *.* to" commands as you seem to ask for before but reject it after, but that was just a possibility (to add or not).
http://www.phpbb.com/phpBB/viewtopic.ph ... 749#682749" target="_blank
http://www.phpbb.com/phpBB/viewtopic.ph ... 835#718835" target="_blank

The fact is that the current Nuttzy's convention about these kind of files is to add a copy instruction for each subSilver files (EM will proceed automatically the other "copy") but in fact there is 3 possible levels.

Level 1 : one general command

Code: Select all

copy phpbb_root/*.* to
+
- easier for developers
-
- not all the detailed command for manual installations (but with the phpbb_root structure it's quite easy to do the right copy, even manually)
- can not be used with non phpbb_root structured files

Level 2 : a copy command by main style/main language file

Code: Select all

copy phpbb_root/language/lang_english/lang_mod.php to language/lang_english/
copy phpbb_root/templates/subSilver/overall_header.tpl to templates/subSilver/
copy phpbb_root/templates/subSilver/images/lang_english/new_button.gif to templates/subSilver/images/lang_english/
+
- current Nuttzy's convention
- less instructions than with the detailed level
-
- not all the detailed command for manual installations

Level 3 : a copy command for each file

Code: Select all

copy phpbb_root/language/lang_english/lang_mod.php to language/lang_english/
copy phpbb_root/language/lang_french/lang_mod.php to language/lang_french/
copy phpbb_root/templates/subSilver/overall_header.tpl to templates/subSilver/
copy phpbb_root/templates/subSilver/images/lang_english/new_button.gif to templates/subSilver/images/lang_english/
copy phpbb_root/templates/subSilver/images/lang_french/new_button.gif to templates/subSilver/images/lang_french/
copy phpbb_root/templates/subGray/overall_header.tpl to templates/subSilver/
copy phpbb_root/templates/subGray/images/lang_english/new_button.gif to templates/subSilver/images/lang_english/
copy phpbb_root/templates/subGray/images/lang_french/new_button.gif to templates/subSilver/images/lang_french/
+
- all the possible command are detailed for manual installation
-
- longer to write for developers

P.S.: notice that with all this level EM can ask (or not if Nuttzy don't want to implement it) if it needs to apply or not specific styles/languages instructions (copy ones and others). So, that's not the problem. EM can always ask for it, and apply copies & others instructions or not, according to the destination directories.

Ptirhiik
Registered User
Posts: 144
Joined: Sun Apr 06, 2003 12:29 pm

Re: 08: Be Style Conscious

Post by Ptirhiik » Fri Sep 19, 2003 1:30 pm

I don't think the deal here is the copy command, but rather the edit command, or more exactly, non-edit command (meaning not applying a part of mod if a similar part exists specificely).

About phpbb dir structure, the more I go on with my mods, the less I use it, having rather a modular structure (meaning tools I add : mods settings for configuration, topics list for topics lists, etc.), and optional part (extensions). I tend to have a real packaging rather a phpBB structure clone, as it won't be convenient nor practical. Language pack are seen as extension of the mod, and are linked also with the language-specific graphics. At end, each have its own mod description, or are included in the main mod description when they are requested on main installation. So the mod is not written in a way convenient for a tool, but rather in a way convinient for functionality : you want this extra feature, install also this part. It won't deal with : you wan't fi template, install this part rather than this one.

Nuttzy99
Registered User
Posts: 927
Joined: Fri Aug 03, 2001 7:09 am
Contact:

Re: 08: Be Style Conscious

Post by Nuttzy99 » Fri Sep 19, 2003 2:51 pm

I haven't read any posts here but I wanted to let folks know that so far the MOD Team members that have looked this over are suggesting I do something different for the directory structures. They are suggesting that the MOD's directory structure mimick the phpBB dir structure. So you would have...

mods/Country_Flags/templates/subSilver/flag.tpl
mods/Country_Flags/templates/blueGray/flag.tpl

...etc., and the same thing for languages. I'm going to need to chew on this for a while. I was planning on taking a break from writing the docs anyway, so good timing for a lengthy discussion ;)

-Nuttzy :cool:
SpellingCow.com - Free spell check service for your forums or any web form!
My Other Site

User avatar
-=ET=-
Registered User
Posts: 213
Joined: Mon May 26, 2003 1:35 pm
Location: France

Re: 08: Be Style Conscious

Post by -=ET=- » Fri Sep 19, 2003 3:26 pm

Ptirhiik wrote:About phpbb dir structure, the more I go on with my mods, the less I use it, having rather a modular structure (meaning tools I add : mods settings for configuration, topics list for topics lists, etc.), and optional part (extensions). I tend to have a real packaging rather a phpBB structure clone, as it won't be convenient nor practical. Language pack are seen as extension of the mod, and are linked also with the language-specific graphics. At end, each have its own mod description, or are included in the main mod description when they are requested on main installation. So the mod is not written in a way convenient for a tool, but rather in a way convinient for functionality : you want this extra feature, install also this part. It won't deal with : you wan't fi template, install this part rather than this one.
I'm not sure to have fully understand what you said :(
All this is what you would like to go?
When you said "Language pack are seen as..." it's not what you know of the future EM release, it's what you think it should be done, no?

So, if I've correctly understand you, this modular approach is interesting.
I've suggest this kind of feature too in the past...
http://www.phpbb.com/phpBB/viewtopic.ph ... 577#700577
...but here you seems to suggest to generalize this approach with a choice for:
- optional MOD feature
- languages instructions (even english)
- styles instructions (even subSilver if you want to keep 1 non MODed style?)

Correct?

That's interesting but it's a new feature and Nuttzy already answer me (about my previous suggest) that he find it interesting too, but he will not implement it until the first final EM release; maybe in a 1.2.0 he said :roll:

About the language style images issue, you suggest to put style image copy instructions in language file instructions which must be analyze by EM to find "_style" extension, that's it?
Why not... :roll:

OK.
If I've well understand you, why not.

IMO, I prefer the phpbb root solution as "for me" it's instead of one directory for each option (functional, language or style) clearer for a large majority of MODs, but both works, it's just a matter of presentation.
For me, the most important is to find easily optional MOD instructions and not to have too many files and dirs in the MOD root dir.
IMO the phpbb root dir must be seen as a common resource structure of files, clearly arranged by location they will have in the phpbb structure if you need to copy them.

But the modular presentation can be convenient in some case too, especially for those who have functional option which need files, I agree.
This will prevent to confuse this kind of file with the rest of the core MOD provided files (which is not the case for style or language files, which will already be in separate dirs in the phpbb root solution).

User avatar
-=ET=-
Registered User
Posts: 213
Joined: Mon May 26, 2003 1:35 pm
Location: France

Re: 08: Be Style Conscious

Post by -=ET=- » Fri Sep 19, 2003 3:33 pm

Nuttzy99 wrote:I haven't read any posts here but I wanted to let folks know that so far the MOD Team members that have looked this over are suggesting I do something different for the directory structures. They are suggesting that the MOD's directory structure mimick the phpBB dir structure. So you would have...

mods/Country_Flags/templates/subSilver/flag.tpl
mods/Country_Flags/templates/blueGray/flag.tpl
lol :D

Why not but IMO this is an hybride solution.
It's not as flexible as your current solution (Nuttzy), and not fully clean for all files as mine.
What about other files which need to go to /includes/ or /amin/ dir?

If they want to respect the phpbb structure, do it for all files! (or don't do it to keep your flexibility as for your's or Ptirhiik's solution) :?
Eternal newbie

Locked