Skip to main content
Topic: Code reworking: directory structure (Read 13413 times) previous topic - next topic
0 Members and 1 Guest are viewing this topic.

Re: Code reworking: directory structure

Reply #15

The main difference between the two is separation per responsibility first (#4) and separation per feature/functionality first (#5). Well in reality they both exist, the difference is how.

Quick summary:
Option #4
  • it groups per responsibility (controller/subs/templates/languages, with tweaks but mainly this way), and that's the definite way forward, for the next two major versions. There's a lot of work to do for it to be even true.
  • the area/feature/'module' are distinguished by naming pattern.  i.e. Karma., Profile. (and further Profile.History, Profile.Info, etc.), within the core
  • it doesn't separate first per 'module'/area, but first per responsibility, per role, and only second, per area/functionality.
  • [big] addons or modules have an example to take (and they will). (they're modules, and within, they separate per responsibility).
  • there is a correspondence kept (in a measure) between the components... .controller <-> .template should be very good mapping, mostly with <-> .language too... with some exceptions. For .subs it's a bit different, there is some, but they are driven by a different need.
    • there is and there will be an impedance mismatch between the user interface [to which controller/template map], and the entities, the objects we work with [boards, topics, etc, which is what .subs mostly "follow"]. (i.e. manage boards, boardindex, notifications or read/unread for boards, messageindex, they all deal with "boards" (and may use Boards.subs for their work.)
    • the library of .subs is not and can never be fully per feature/functionality/user interface-available functionality, but it serves them all (/lib, as it is in option #4). It's loosely the 'M' for 'model', and model doesn't obey to them interface rulez.
  • core features (I didn't mention this (sorry)), are also candidates for addons/modules. I'll come back on this. We separate them and use (of course) naming patterns and the associated redesign as necessary for them, aka Calendar, Karma [.controller, .template, etc]

I admit... I see other considerents too... The separation per responsibility (if we make it the best) will allow us to look into distributions for Debian or other Linux systems easily... This is also a target for me (still unlikely for first version, we'll see, but as soon as possible).
Last Edit: December 23, 2012, 03:59:34 am by TestMonkey
The best moment for testing your PR is right after you merge it. Can't miss with that one.

Re: Code reworking: directory structure

Reply #16

Quote(10:49:24 AM) Norv: When you make a custom theme and need text strings, do you add a new language file for them, or do you modify one of the core language files?
(11:36:54 AM) Antechinus: Depends
(11:37:23 AM) Antechinus: If wanting to get it approved at SMF would use a ThemeStrings file
(11:37:49 AM) Antechinus: If just for use on a mono-lingual site, would hard code the text
(11:38:07 AM) Antechinus: which is easier and is better for performance
Apart from the funny side of it :), none of the options is "modify the files included in Themes/default/languages". Inquiring minds want to know then:
QuoteJust put all languages files in the default/languages directory. Jesus, are you trying to make the whole thing incomprehensible?
What exactly is incomprehensible, about /languages in /Sources?
Sources/languages vs Themes/default/languages is a 2 level path vs a 3 level path. ;)

Or, is it incomprehensible if language files are split in admin module? (Sources/admin/languages)

To note:
# $languagedir has been defined for a long time. It allows to not hardcode the path to languages (for mods).
# to load a language file you use good ole' loadLanguage(). Not write down the path.
# there is no issue with adding a language file in a custom theme, no matter if the default main distribution has languages in the theme or it doesn't.
Last Edit: December 23, 2012, 05:11:44 am by TestMonkey
The best moment for testing your PR is right after you merge it. Can't miss with that one.

Re: Code reworking: directory structure

Reply #17

Quote from: TestMonkey – Apart from the funny side of it :), none of the options is "modify the files included in Themes/default/languages".
Themes installer doesn't allow to do any change to existing files, so even if you want to, you cannot. ;)

Quote from: TestMonkey – What exactly is incomprehensible, about /languages in /Sources?
Ant wants everything in theme so he can mess with it if he wants! :P
Last Edit: December 23, 2012, 05:17:19 am by emanuele
Bugs creator.
Features destroyer.
Template killer.

Re: Code reworking: directory structure

Reply #18

QuoteAs for the caps on the directories or not ... ummm not sure really ... Maybe caps on our base level and lower for the subs? Today its a mix of, well everything :P
To be honest, the only reason why I'd keep the capitalization on base directories is historical.
The best moment for testing your PR is right after you merge it. Can't miss with that one.

Re: Code reworking: directory structure

Reply #19

It looks nicer. :P No, I'm not joking. It really does.

Quote from: TestMonkey – What exactly is incomprehensible, about /languages in /Sources?
Sources/languages vs Themes/default/languages is a 2 level path vs a 3 level path. ;)

Or, is it incomprehensible if language files are split in admin module? (Sources/admin/languages)

To note:
# $languagedir has been defined for a long time. It allows to not hardcode the path to languages (for mods).
# to load a language file you use good ole' loadLanguage(). Not write down the path.
# there is no issue with adding a language file in a custom theme, no matter if the default main distribution has languages in the theme or it doesn't.
IF you put languages in Sources then you'll have odd ones out (the theme languages files) or you'll have to make the theme installer write to Sources, which would involve creating extra folders in there for each theme that had a custom file.

You are aware that themes commonly have languages files included even if they don't use ThemeStrings.***.php as such? It's very common to include Settings.****.php in themes. It's rare for them to not have it, so what so you intend to do about that one?

Do you propose to load most but not all languages from Sources, and some but by no means most from individual theme folders? What about the admin centre languages editor? Are you going to make that write to Sources for default themes but write to indivdual theme folders for things like Settings.***.php? More to the point, what is the practical benefit of moving everything if you don't have to? In case you haven't noticed, it already works. :P
Master of Expletives: Now with improved family f@&king friendliness! :D

Sources code: making easy front end changes difficult since 1873. :P

Re: Code reworking: directory structure

Reply #20

Quote from: emanuele – Ant wants everything in theme so he can mess with it if he wants! :P
The whole idea of having a theme system is so you can mess with stuff. :P
Master of Expletives: Now with improved family f@&king friendliness! :D

Sources code: making easy front end changes difficult since 1873. :P

Re: Code reworking: directory structure

Reply #21

Ant, I have already answered to some of the questions. And I will say this from the start: if what you are saying is that you think it's a "problem" to set a path to language files and load them from there, you have to be kidding.

First, I will answer per each though. To be clear on them.

Quote from: Antechinus – IF you put languages in Sources then you'll have odd ones out (the theme languages files)

#1. Mods already have what you call "odd ones out": the mods language files. Are they "odd"?

It sounds like habit of thinking to me. Just because you're used to one, you call "odd" a different idea.
In case it isn't clear, and it seems by your answers, that it isn't, I'll repeat what I said several times only in this topic: habits of thinking matter too. But don't claim they're grounded in a different actual reasoning, when they are not.

#2 .
Quote from: TestMonkey – To note:
# $languagedir has been defined for a long time. It allows to not hardcode the path to languages (for mods).

I will note, customizability of $languagedir is not implemented in the core software, it's there only for mods installer.

Quoteor you'll have to make the theme installer write to Sources, which would involve creating extra folders in there for each theme that had a custom file.
Out of the question for me. Theme installer shouldn't write to /Sources.

QuoteYou are aware that themes commonly have languages files included even if they don't use ThemeStrings.***.php as such? It's very common to include Settings.****.php in themes. It's rare for them to not have it, so what so you intend to do about that one?

Quote from: TestMonkey – # there is no issue with adding a language file in a custom theme, no matter if the default main distribution has languages in the theme or it doesn't.

There is no issue with adding them means there is no issue with the core loading them. We load custom themes from random locations. And by that, we load already /custom_location/languages.

QuoteDo you propose to load most but not all languages from Sources, and some but by no means most from individual theme folders?
Here's what happens today: the core loads most but not all languages from a single location, and some but by no means most from individual theme folders.
Here's what happens today: the core loads default language files from a default location, and mods language files from wherever they are, in their own directories. All over the place.

QuoteWhat about the admin centre languages editor? Are you going to make that write to Sources for default themes but write to individual theme folders for things like Settings.***.php?
If your question is about any implementation details, such as pick the right path, then I've already answered several times above.


To summarize:
You have to be joking if you're making a fuss over the code choosing a path. We're doing it all the time, you know. We're choosing the path to default_theme/languages from a variable in the database. It doesn't happen by telepathy. :P



IMO, there is a real problem on the last bit you mentioned, but it's different: it is that people might secure their /Sources location more than /Themes.
That, yes, it's a concern, and one I wouldn't take lightly. It's implied already in the OP, in the constraint I mentioned. But it's also the other way around: on the contrary, I've been considering to change the directory structure such that we can separate fully files that have to be accessible from the web directory, and those which can be in any location. That's yet another aspect, and the way themes are structured actually makes it more difficult.
My next questions here will be: is the feature of editing languages commonly used? Afaik the answer is: no, but it sometimes is.
And: do we have a way, to be able to use the 'make files writable only for this session'? The answer is: yes.



Quote from: Antechinus –
Quote from: emanuele – Ant wants everything in theme so he can mess with it if he wants! :P
The whole idea of having a theme system is so you can mess with stuff. :P

Again, you don't mess with default language files in a custom theme anyway. So this "argument" says something moot.

Sounds like you have the impression that their location would "prevent" you from doing I-don't-know-what-but-it-has-to-be-something-so-Ill-yell, when it does not. (possibly - or not - exception made for the note above).

On the contrary. One of the driving points why I opened this thread is to open for discussion what we can do on the directory structure, for many reasons, including customizability, in particular for addons. Because they are the ones that, by editing directly code and in particular theme code, mess up installations with custom themes and are unable to install and all that yada-yada. Note that the theme system is not the "innocent" here either: the theme installer directly copies files, and the template loading directly overrides the default.

The languages location is a very small point in the big picture of that, a point which I opened for discussion. Reasons for it are related to: separation of the codebase into logical and customizable folders (/languages should be fully customizable, location interchangeable), the example we provide to third-party developers (see the gallery addon example), consistency of directory structure, precisely the attempt to allow more files and folders to be inaccessible from the web directly (albeit in this case a trivial point), and what's more, because internationalization doesn't and shouldn't be dependent on themes (not even on location). (images excepted, obviously). I also have in mind linux distributions, and a couple of others.
The best moment for testing your PR is right after you merge it. Can't miss with that one.

Re: Code reworking: directory structure

Reply #22

Quote from: TestMonkey – #1. Mods already have what you call "odd ones out": the mods language files. Are they "odd"?

Here's what happens today: the core loads most but not all languages from a single location, and some but by no means most from individual theme folders.
Here's what happens today: the core loads default language files from a default location, and mods language files from wherever they are, in their own directories. All over the place.
All the mod languages files should be in the Themes/default/languages folder at the moment, or in a sub-folder of that. They shouldn't just be all over the place. If they are, someone has screwed up.


QuoteOut of the question for me. Theme installer shouldn't write to /Sources.
Well you would still need to have the admin centre laguages editor writing to Sources then, and you would presumably still have mods writing to Sources as well. So, if you are thinking of integrating the themes installer and the mod installer, you will still need some way of differentiating theme from mod. Not that it can't be done, just noting it.


QuoteIMO, there is a real problem on the last bit you mentioned, but it's different: it is that people might secure their /Sources location more than /Themes.
That, yes, it's a concern, and one I wouldn't take lightly. It's implied already in the OP, in the constraint I mentioned. But it's also the other way around: on the contrary, I've been considering to change the directory structure such that we can separate fully files that have to be accessible from the web directory, and those which can be in any location. That's yet another aspect, and the way themes are structured actually makes it more difficult.
My next questions here will be: is the feature of editing languages commonly used? Afaik the answer is: no, but it sometimes is.
And: do we have a way, to be able to use the 'make files writable only for this session'? The answer is: yes.
I agree that moving as much out of the web directory as possible isn't a bad idea. The language string editor is quite handy though, so it would be preferable to keep it.


QuoteOn the contrary. One of the driving points why I opened this thread is to open for discussion what we can do on the directory structure, for many reasons, including customizability, in particular for addons. Because they are the ones that, by editing directly code and in particular theme code, mess up installations with custom themes and are unable to install and all that yada-yada. Note that the theme system is not the "innocent" here either: the theme installer directly copies files, and the template loading directly overrides the default.
Yeah sure, but to my mind there is just some stuff that some people will want to do that will not be instantly compatible with other stuff that other people want to do, or may already have done. Past a certain point, some people will need to learn a bit of coding. Things happen.

So, while certainly providing hooks etc to minimise the problems is a good plan, I don't think there's any virtue in getting so paranoid and protective that people are restricted when they do want to do something unusual. If a user doesn't like the result, they don't have to install that theme or mod.


Quote...because internationalization doesn't and shouldn't be dependent on themes (not even on location). (images excepted, obviously). I also have in mind linux distributions, and a couple of others.
Well the i18n will still be dependent, to a minor degree (or not, depending on the themer) upon the theme having the right versions of any custom strings. Don't think there's much that can be done about that.

Side note: that silly old code for the "use image buttons" option. Has that been removed everywhere already? I know it's all over the place in 1.1.x but am not sure if it all went in 2.0.x. If it didn't, it should. Nobody in their right mind will ever use it (CSS is a much better option).
Last Edit: June 11, 2013, 08:18:55 am by TestMonkey
Master of Expletives: Now with improved family f@&king friendliness! :D

Sources code: making easy front end changes difficult since 1873. :P

Re: Code reworking: directory structure

Reply #23

For the record, this is a rough experiment for the following purposes:
  • make /www directory for publicly accessible files
  • separate assets from code (recommended practice anyway, and favorite practice by automated builders)

https://github.com/norv/Dialogue/tree/dirs_test7

ETA: the existence of /www/assets directory means it can hold the combined css/js files. (www/assets/hive or www/temp)
Last Edit: December 26, 2012, 03:23:03 am by TestMonkey
The best moment for testing your PR is right after you merge it. Can't miss with that one.

Re: Code reworking: directory structure

Reply #24

Call on capitalization please. As it stands, /Sources, /Themes, and /Packages at a minimum (/Smileys currently too), are capitalized.

Yes or no? (yes = keep capitalization, no = drop, all lowercase)

Last changes: (version #4 with tweaks)
https://github.com/norv/Dialogue/tree/dirs_test6
The best moment for testing your PR is right after you merge it. Can't miss with that one.

Re: Code reworking: directory structure

Reply #25

I'd like to wrap up this discussion. There isn't a full consensus. But, lets see what we can do.
I will state from the start though: in the #4 vs #5 choice, I think #4 with some tweaks (known as #6) is more appropriate.


One point, in support of option #4, heading towards a different way to look at option #5:

Still in mind with the next two major versions: one important thing we are pursuing, from 1.0, is introduction/reworking of mechanisms to faciliate plugging in seamlessly (a big "subsite" addon, as well as a database layer, as well as a core feature).
Gedanken experiment: add a /addons directory to the root, and have Gallery, [Social]Profile and Calendar in it. They all build your site.
=> a somewhat similar result with both "options". We already have mechanisms to load seamlessly (atm limited to loading from /sourcedir but that will change).
https://github.com/norv/Dialogue/tree/dirs_test6

It's built on option #4 with a few tweaks. All addons we are working on (official) have their place for all their files.


IMO option #4 (#6) is clean and appropriate. For the codebase, what we work on it, where we move it - please keep in mind we visually separate 'Component'-'Area too.

More importantly... how do I put this. I will state my personal perspective. Directory structure is not alpha and omega, but it matters, and for the moment (given the codebase status and way we work with it, too) I do give it a particular significance:

Software has an identity, an 'inside look' of its own, which is tightly related to the code design, the architecture as implemented in code. It can have its occasional wth, and any experiment with it is welcome, but overall its results have to have 'that feeling', the identity, the specific of this software.
Option #5 does not. It's too much of a jump on the codebase, and it has the feeling of the symfony bandwagon. Modularizing is one, jumping that bandwagon is different. In plainer English, it's java bandwagon in php, at the level of code design - and it probably implies it at the level of [single class] code too. And that bandwagon has a high price (take a good look at how symfony decouples the code to be able to fully separate 'components', small example). I admit I'm not willing to pay it.

That's a rough way to say it, but it's all about what we want for the entire application. Loose coupling is fine, no coupling is another cup of tea altogether. I do not think we even want to try to build components, fully decoupled and fully replaceable with others doing the same thing: the main parts of the application are designed to work together (they directly depend on one another), not to work with everything else under the sun.
This isn't strictly related to directory structure (obviously we could easily have some variant #5, and not implement it that way; by the way remember /auth), but I admit that in my perspective, for now, for the next version (and if we follow our intentions to stabilize 1.0 fast, then for the next as well), it's this way:
  • if we pursue #5, I agree it's too far of a jump and it feels, to me, like it's not an internal necessity of the codebase, but a temptation to jump that bandwagon.

I think #6 is the way to go, with or without a tweak like those capital names. Please do let me know what you want on that one. :)


If there is strong support for #7 ( http://www.elkarte.net/index.php?topic=74.msg539#msg539 ), then that would be perhaps worth playing with, and we can delay this decision until we settle it. But I should note, nothing is stopping us from implementing in the installer choices for directories like /Sources and /attachments base directory, which would help a bit even #6 to encourage admins to use non-public directories.
Last Edit: December 26, 2012, 05:24:33 am by TestMonkey
The best moment for testing your PR is right after you merge it. Can't miss with that one.

Re: Code reworking: directory structure

Reply #26

Number 6, the test formally known as 4, looks good to me

I thought number 5 was my least favorite until I saw number 7 ....  I dislike 5, I abhor 7

I'd guess I'd vote for all lowercase at this point as I can't come up with a good reason (other than legacy) for leaving just a handful of them like that with the rest all lower.

Re: Code reworking: directory structure

Reply #27

Gotta admit I prefer capitalised just for aesthetics, but it's not a big deal to me either way.
Master of Expletives: Now with improved family f@&king friendliness! :D

Sources code: making easy front end changes difficult since 1873. :P

Re: Code reworking: directory structure

Reply #28

Agree with the Potato man here. I like option 6 the best. Number 7 and 5 need to die by fire.
Success is not the result of spontaneous combustion, you must set yourself on fire!