Revision [3267]
This is an old revision of WikkaCodeStructure made by JavaWoman on 2004-12-15 21:33:15.
Wikka Code Structure
A few days ago I had a little discussion with JsnX in TheLounge (the #wikka channel on irc.reenode.net) about "external" type programs (not part of Wikka but providing important functionality), actions, plugins... and how to organize it all better into a directory structure. I'd been thinking about the same things myself, but somehow didn't quite pick up on what JsnX was proposing (I was probably "multitasking" and doing other things while talking to JsnX on #wikka, sorry).
So, I'll now try to take it from there and give a worked example of what I had in mind (and possibly JsnX as well).
Rationale
My rationale for this proposal is as follows:- Keep "third-party" (external) code together in a directory that indicates it's not part of Wikka's source code but "bundled software".
- Maybe make a distinction here between "core" (needed for basic functionality) and "optional" (may be turned off in configuration); while we have only a few packages of third-party code now, this could increase, so I think this is a good moment to make the distinction to avoid another restructuring down the road.
- Separate actions into "core" (actual "wiki" type of functionality) and "plugins" (nice optional extras, but not necessary to run a wiki site).
Proposal
[wikka]/ [wikka]/3rdparty/ [wikka]/3rdparty/core/ [wikka]/3rdparty/core/geshi/ #I'd say this provides core functionality, could be debatable though [wikka]/3rdparty/plugins/ [wikka]/3rdparty/plugins/freemind/ #cannot be turned off yet but is not needed functionality [wikka]/3rdparty/plugins/safehtml/ #can be turned off globally [wikka]/3rdparty/plugins/wikiedit2/ #can be turned off globally [wikka]/actions/ [wikka]/actions/core/ # "overall management" actions (referring to other pages than the current one) [wikka]/actions/core/category.php [wikka]/actions/core/highscores.php [wikka]/actions/core/interwikilist.php [wikka]/actions/core/lastusers.php [wikka]/actions/core/mychanges.php [wikka]/actions/core/orphanedpages.php [wikka]/actions/core/ownedpages.php [wikka]/actions/core/pageindex.php [wikka]/actions/core/recentchanges.php [wikka]/actions/core/recentcomments.php [wikka]/actions/core/recentlycommented.php [wikka]/actions/core/textsearch.php [wikka]/actions/core/textsearchexpanded.php # page structure rather than content [wikka]/actions/core/footer.php #should this really be an "action"? [wikka]/actions/core/header.php #should this really be an "action"? [wikka]/actions/core/nocomments.php # page content (or referring to/changing the current page only) [wikka]/actions/core/backlinks.php [wikka]/actions/core/color.php #remove colour.php or include colour.php that only does an include of color.php: don't have duplicated code! [wikka]/actions/core/include.php [wikka]/actions/core/image.php #and disallow dynamic image inclusion via url: not valid html [wikka]/actions/core/lastedit.php [wikka]/actions/core/table.php [wikka]/actions/plugins/ # system management [wikka]/actions/plugins/emailpassword.php #access control may not be desired/implemented [wikka]/actions/plugins/usersettings.php #access control may not be desired/implemented [wikka]/actions/plugins/feedback.php # page content [wikka]/actions/plugins/calendar.php [wikka]/actions/plugins/files.php [wikka]/actions/plugins/flash.php [wikka]/actions/plugins/googleform.php [wikka]/actions/plugins/iframe.php #now in intranet dir: it's really an action! (I think it's there for security reasons, so it can't be used except deliberately. -- GMB) [wikka]/actions/plugins/mindmap.php [wikka]/actions/plugins/rss.php [wikka]/css/ [wikka]/docs/ [wikka]/formatters/ [wikka]/handlers/ [wikka]/images/ [wikka]/setup/ [wikka]/xml/
Notes
- Apart from separating actions into "core" and "plugin" I've grouped them by general functionality (embedded comments)
- Since "plugins" would be optional elements in a working Wikka implementation, WikiAdmins will need a way to activate or deactivate them. This suggests a kind of "plugin registry" (a new database table) with some admin-only functionality to register, activate, deactivate and unregister a plugin.
- To execute an action, existence of the action should be checked (in the defined path) as well as whether a plugin is registered and activated (no action if these criteria are not met)
- WikiEditor WikiEdit2 and SafeHtml "activation" are now done via the config file; this should be implemented via the proposed plugins registry instead. (In addition, if WikiEdit2 is activated, it would be nice if a user could choose to turn it off in their own profile).
- Freemind cannot now be (de)activated; this can be accomplished by a registry entry for the mindmap action which implements Freemind in Wikka.
- The directory intranet which now contains iframe.php should disappear: it really is an (optional) action.
- I think the (buggy) newpage action should disappear as well: apart from buggy it's redundant, there are already two other methods to create a new page.
- The configuration should define the paths where all types of actions can be found.
- Since the third-party applications we bundle may already exist on a WikiMaster's system, paths and implementation parameters for these should not be hard-coded in the Wikka source code but instead be defined via parameters in the configuration file. This will give the WikiAdmin the option of using the already-installed (and maybe modified!) program to maintain consistency on her system.
Comments?
Comments and better ideas welcome, of course.The idea is very welcome. I was also thinking of a possible overhaul for the Wikka directory but finally never posted it: I'm glad to see that someone else has come up with a similar idea :) I like your general sketch, I only find the idea of separating 3rd party contributions in core vs. plugins not that convincing. And what about a better name for 3dparty/? Maybe libs/ ? --DarTar
Actually, JsnX came up with:
external, include, 3rdparty, ??and I thought both "external" and "include" rather vague, and 3rdparty quite descriptive (something we also used in a company I worked for for the same purpose) - so that's what I picked here. Your "libs" might also work, or maybe "bundled"? As long as it's a reasonably descriptive name...
I'm expecting that at one point we'd bundle both "essential" (core) and "would be nice" (optional) apps, so
preparing the directory structure now would save another round of restructuring later. Do you see any problem with that structure (even if we leave one empty now), DarTar?
I think the advantage of 3rd party versus libs is this....if I download and use a package I assume that it's reasonably well tested by a team of developers. If I install a "3rd party" add-on I expect (i) poorer documentation & (ii) more possible conflicts. If a 3rd party add-on doesn't work, I "blame" the developers...well, not really....but you get my drift. If something says "libs" tho', that carries the cachet OF the main developers. I'd say leave it as "3rd party" so that the source of the add-ins is abundantly clear and their developers will be contacted for help and not the wikka developers. -- GmBowen (somebody who keeps dumping "inessential" 3rd party add-ons onto the wikka site...wait'll you see the latest ; ) )
I think it's a matter of trust, really. Do you trust the Wikka developers?
For me, "3rd party" signifies clearly something that's not made by Wikka developers, but if you trust the Wikka developers you'd know they wouldn't include a 3rd party library or application that's not at least useful and reasonably bug free - as well as Open Source (so if you do find a bug you can repair it!); and you'll also know that for support for that program you shouldn't look at the Wikka developers but go to the developers of the bundled app. Essentially "3rd party" means: "it's not ours but it's good enough that we use (and recommend) it!". (And in open source we try to avoid re-inventing wheels.) "Libs" does not have that connotation. So I think we agree on that - but I could live with "libs" if that gets a majority vote :). --JavaWoman
I'm not sure that I trust the Wikka developers. They seem a bit shady to me. But, JavaWoman, your last comment above is right on target. When I see the word "libs", I think of library files that are tied to the application. "3rdparty" sounds more like software that was developed by a 3rd party--weird, huh? :). JW, thank you for adding this page, it nicely documents the fuzzy idea that I had in mind. Excellent work. -- JsnX
I like it too. The only thing I would change is putting usersettings in the core. I think them to important to be just a Plugin! NilsLindenberg
Nils, I put them in plugins like I put everything to do with user accounts in plugins; my reasoning was that you can use a Wiki (including Wikka) by having it open to everyone, and not have user accounts at all, so in that sense it's optional. OTH, we could emphasize the fact that Wikka has access control by classifying them as core. Which message do we want to give out? --JavaWoman
Seems to make sense :-) Nils