New MODDB requirements: separate modx file for templates?

[igorw]

Hello,

first of all, sorry for posting this in the 3.0.x discussion, maybe it can be moved to the 3.0.x mod authors later. I have a question about the new moddb requirements.

2.b. states that:

No template changes in main MODX file, all changes in /templates as described in the MODX packaging format specifications.

Now does this mean thatwe have to put all style/template related changes into a separate modx file in the /templates folder? I'm just a little confused about this, because for 2.0.x so far we could include the subSilver changes in the main modx file. I thought the /templates folder was for additional template files. The way this "requirement" is worded, it seems that prosilver/subsilver2 changes need to go in there.

I would like some clarification, and - if you don't mind - some discussion!

Thanks!

[DualFusion]

Hey Igor, I was asking you about this too about a minute ago. May I add something else to this? Would we put prosilver and subSilver2 changes in the main modx file, or just prosilver in the main modx file and subSilver2 in /templates, or ALL changes in /templates?

[Prince of phpbb]

From MODX packaging standards - 5.4

The templates folder allows you to include additional MODX files for target applications that support
templates. Each MODX file must have code for modifying a single template, and have the same name
of the template, which it is modifying. For example for the phpBB2.0 template subSilver,
‘subSilver.xml’ would add changes to that template

Yes, in phpBB 2.0 we used to put it in the .mod file but *i think* for MODX, all the template changes will have to go in templates folders. Moreover, for phpBB3, default style is proSilver but if you will want to add changes for both styles (proSilver and subsilver2), you will need to create separate files for each style ..

[BondGamer]

Also, what about ACP template changes?

[geoffreak]

Also, what about ACP template changes?

Last I checked, only one ACP template allowed at any given time

[poyntesm]

I am in the confused ranks too!! Not sure if prosilver goes there or in root?

Also should the folder only include the .xml file or should the template files and other style files such as theme and imageset be in there or in root?

[smithy_dll]

Example hierarchy

Code: Select all

install.xml
languages/nl.xml
languages/root/theme/prosilver/imageset/button.png
root/new_page.php
templates/prosilver.xml
templates/root/theme/prosilver/template/new_page.html
templates/subsilver2.xml
templates/root/theme/subsilver2/template/new_page.html

Do as the specification says to the letter. Some of the references to theme names are old or non-existant. But the text is purely an example.

No template changes in main MODX file

It means exactly that, no exceptions are given. No exceptions are written. Nowhere written is anything that could be confused for an exception.


As for phpBB2.0. It was distributed with a single template, phpBB3.0 is distributed with two. Do not interpret phpBB2.0 into phpBB3.0. The rules of the game have changed in order to better accomodate the new playing field.

The MODX docs are purposely general and refer to phpBB minimally. They purely describe the MODX format. They do not describe additional requirements the phpBB Modifications team requires on top.

[igorw]

Thanks for your reply smithy_dll, and also thanks for all the other replies!

This really seems to be a big change that doesn't seem to be documented very well... I think that in documentation written for the moddb (not written for MODX in general), there should be some examples for how it looks in phpBB (like you provided), because that gives us mod authors a better idea. And it saves the mod team having to deny the first wave of MODs because of wrong packaging (allthough i bet there will be other problems too, but then at least deny with a good reason ).

So now, if you have:

Code: Select all

languages/nl.xml

Will we have to duplicate the MODs header section into that file? That file is pureley for the language edits (but english is included in the main file as i understand it), and the languages/ folder can also contain image files for alternative images, which brings me to my next question (about your example):

Code: Select all

languages/root/theme/prosilver/imageset/button.png

I think this should be languages/root/theme/prosilver/imageset/nl/button.png since if it's language specific it shouldn't go in the non-localised (main) imageset folder.

The same question that was asked above for /templates/, do we need a full MOD header for this modx file? Because that's quite a lot of work, and i don't consider it a separate MOD, it's part of the modification as whole. This is more relevant than languages, as it applies to all MODs, since phpBB3 has two templates (styles actually ). Having additional languages in a separate folder makes sense to me, because the only language phpBB3 comes with is english. But for the styles i don't think so. There may be differen't styles for phpBB3-out-of-the-box, but i think that they should be in the /root/ folder, because they were included with phpBB3. /templates/ makes sense for additional templates/styles not included with phpBB, if you wish to support them. It's what we guys used to put in the contrib folder (which was fine too :p).

And to add some more discussion to this topic (i hope you don't mind), what do you all think about this "change"? I consider this a change, because i didn't have to package my MODs this way for phpBB2, which were also using MODX (perhaps not "correctly"). I personally find the example structure very confusing. Not only for the MOD authors, but also for the people installing the MODs. They no longer can go through their actions in one go and copy all files from /root/ to root, they have to open up another another file and copy files from another folder... it's just very complicated. I personally liked the change to XML very well, because it's easier for computers to read, and it's easier to style, which you did a great job on with prosilver. I've already had a few confused users, who didn't know how to open the MODX file, you explain, they learn, or you tell them to look in /contrib/. But now it's starting to confuse me

Another thing, there's still an unanswered question:

Also, what about ACP template changes?

Those are also template changes, but i guess as there's only one single ACP style, we will be able to include them in the main xml...

[poyntesm]

Smithy,

Sorry for all the questions. You will have to bear with us as the first few always do the learning and questioning

The current documentation for MODX states the XML in the root directory

The MODX file must only
edit the default template of the target application, and the language it is natively distributed in.

.

So from that I would expect my XML in /root/ to edit for prosilver & english.

However your post makes me think that all prosilver edits & included files get handled via /templates/prosilver.xml & /languages/en.xml

Can you clarify? Is the documentation wrong?

Is the normal intended process for the user to process three XMLs? With the first having edit actions to install the MOD and really the second two just having copy actions to get style and language?

1) /root/your_mod.xml
2) /language/their_chosen_language.xml
3) /templates/their_chosen_style.xml

Again sorry if you think its clear but for me its not.

Esmond

EDIT: Evil beat me as I typed, but you can see we are wondering the same things.

[naderman]

Yes there appears to be an error in the documentation. Each template needs its own MODX file in templates/. The ACP template changes can be made in the main MODX file because it is no longer possible to change the ACP template in phpBB3 so you are guaranteed to find the default template in /adm/style/ (or rather people who modify it, will have to deal with problems themselves).

[poyntesm]

Thanks, although wish the documentation was right

Three MODX files seems like serious overhead for the end user. OK so I can link to one XSL file from each of the three XMLs, but what if the user messes with structure? We all know they should not ... but reality is often different.

Also rather than now just telling a user to upload /root/ which they often struggled with we now have three sets of files for them to upload. Users struggle with stuff like lcd versus cd in FTP. I can see the thinking behind the approach and to a large degree I like it. Its the practical reality that worries me. The idea of install MOD, chose language and style is very nice ... the processing of three XML files and most likely uploads from three locations is not soo nice.

EDIT: Bug submitted for documentation

EDIT PART DEUX : Also would it make sense to append the language for the MODX files. So /youmod-en.modx, /template/prosilver-en.modx ?? That way you could distribute your MOD with multiple XSL file and then have the XML call the correct language XSL? Or maybe I totally misunderstand how we will handle providing the install in different languages??

[Eelke]

Users struggle with stuff like lcd versus cd in FTP.

If you ask me (and I know you didn't ) I'd say that users who struggle with the difference between cd and lcd should have no business installing MODs. In fact, I'd say they should have no business running forums, but that's probably a little too idealistic...

[poyntesm]

Well since you responded I will too . To a certain degree we have to deal with reality, we all know end users are confused often by the MOD format in its old way. The 'copy' action was often not really understood, they got confused with the whole from/to & local v's remote issues.

So for me currently I will be requesting my MOD users to do the following for just a default install (prosilver & english[en]), as we have core code, style non lang files, style lang files & lang files.

Code: Select all

/root/*.*/ -> /{FORUM_ROOT}/
/templates/root/styles/prosilver/*.* -> /{FORUM_ROOT}/styles/prosilver/
/languages/root/styles/prosilver/*.* -> /{FORUM_ROOT}/styles/prosilver/
/languages/root/languages/en/*.* -> {FORUM_ROOT}/languages/en/

I have to be specific on the source as I will ship also with subsilver2 support & hopefully some major language translations.

My MOD users will also have to process the following MODX files which will give them edit instructions & the instructions to perform the above copies.

Code: Select all

/MOD.xml
/templates/prosilver.xml
/languages/en.xml

So you can see (I hope) that it ends up being not so straight forward and I think if a MOD author thinks that, then previously MOD install challenged users will . Anyway guess I have voiced my concerns and I should leave it at that. Although would be very interested to hear the MOD teams response, I am sure they have fully thought it through and might explain the reasons or link to existing posts that counter some of my criticisms.

[poyntesm]

OK one final question (I think )where does the data which is both style specific & language specific stuff go? I am talking about /styles/prosilver/imageset/en/ ... so in there we have files that are language specific & style specific.

So when it comes to the copy action which MODX does it come from? The language one or the style one?

Currently I have the files under langauges ... so I have as follows.

Code: Select all

/languages/root/languages/en/
/languages/root/styles/prosilver/imageset/en/

The copy is performed from the en.xml, but then the en.xml is specific to prosilver. If I move the copy to the prosilver.xml then its langauge specific ... which defeats the purpose to split all this?

I could move the files to the style side

Code: Select all

/styles/root/styles/prosilver/imageset/en/

If I keep the copy in en.xml it will need to be structured as

Code: Select all

		<copy>
			<file from="../templates/root/styles/prosilver/imageset/en/*.*" to="./styles/prosilver/imageset/en/" />
		</copy>

Does any of this make senes?? Either way you end up with the language & style MODX files not being totally independent? Am I missing something?

[igorw]

On IRC smithy stated that english language could be included in the main file. At least that's how i understood, please correct me if i understood it wrong