Forum OpenACS Improvement Proposals (TIPs): TIP #12 (Implemented): New package directory structure

In continuation of the thread over here:

https://openacs.org/forums/message-view?message_id=109480

Here's what I'll propose based on that thread and the current state of HEAD in the CVS tree:

/tcl
/www
/www/admin
/www/sitewide-admin
/www/doc
/www/resources
/lib
/test
/sql/oracle
/sql/postgresql
/catalog

/www/sitewide-admin
-------------------

Files in this directory are intended for site-wide package configuration, pages that summarize across all packages on the system, etc.

The file

SERVICEHOME/packages/my-package/www/sitewide-admin/some-page.tcl + .adp

Will be served for the URL

http://site.com/acs-admin/package/my-package/some-page

This page will only be available to site-wide admins.

/www/resources
--------------

This is for graphics and other files that we wish to serve more efficiently by skipping permissions checking and processing.

The file

SERVICEHOME/packages/my-package/www/resources/my-image.jpeg

Will be served for the URL

http://site.com/resources/my-image.jpeg

They will NOT be processed, e.g. if you put a .tcl file in there, we will not execute it, we will return the source code to the browser in raw form.

They will NOT be served normally through the mounted package, e.g. the URL

http://site.com/my-package-mounted/resources/my-image.jpeg

Requesting the above URL will result in a

403 Forbidden

return code.

/lib
-----

This is for include chunks (tcl + adp pairs), master templates, etc.

It is NOT called /template, because /template suggests that you only put templates here, which is not correct. You can put templates, but typically you would put complete tcl/adp pairs.

The file

SERVICEHOME/packages/my-package/lib/some-template.tcl + .adp

Can be included by the same or another with the following tag in a .adp file:

<include src="/packages/my-package/lib/some-template">

/test
-------

This is for defining test cases for automated testing of the package.

It works like the /tcl directory in that you put files like

SERVICEHOME/packages/my-package/test/my-procs.tcl

and

SERVICEHOME/packages/my-package/test/my-init.tcl

You can watch -procs.tcl files in here.

The only difference is that files in this directory are only sourced if automated testing is enabled for the server. There will be some parameter to handle that.

We're planning to catalog parameters that deal with production versus development/testing, and post a separate TIP with the result.

Now ... vote, please!

/Lars

Approved.
Collapse
Posted by Jun Yamog on
Ok.

Now I have to change my convention...

Collapse
Posted by Jeff Davis on
If the resources directory can't be served from the mount point why not put it outside the www directory rather than
modify the code to force a 403 return?
Collapse
Posted by Lars Pind on
(Note, I changed the TIP to add the /catalog directory)

Jeff, I like your suggestion. The reasoning behind putting it under www/ is that it contains requestable pages.

/www/doc and /www/sitewide-admin work roughly the same way, although it's true you can get to the pages through a mounted package.

Hm.

I don't have any strong opinion on this.

/Lars

Please ignore my vote. I must've thought I was  on the core team in a moment of wishful thinking :)
Collapse
Posted by Dave Bauer on
I agree with Jeff. If they can't be served from a mounted package instance, put them outside www.

What is the reasoning to disallow requests of /mountedinstance/resources/ ?

Collapse
Posted by Lars Pind on
The reasoning is that, in return for files under resources being available to anybody with no permission checking, we also do no processing on them, so we don't have any risk that they do anything bad on the server.

However, if you request them from /mountedinstance/resources, they *do* get executed.

So either we can

1) live with it, which I think is confusing and dangerous

2) have them not be processed when requested as /mountedinstance/resources, which is trickier than just not serving them, and is more likely to cause potential confusion with developers who don't understand why their .tcl file doesn't get executed.

3) refuse to serve them, which I prefer because it's the easist to implement

If we move it to /resources, then that's even simpler.

/Lars

Collapse
Posted by Roberto Mello on
I also prefer if resources is not under www.

-Roberto

Collapse
Posted by Jade Rubick on
What happens if you have two packages with /resources/one.gif

This browser would cache these, and give you inconsistent results, wouldn't it?

And what if you actually have a resources directory under ROOT/www?

How will this work?

Collapse
Posted by Lars Pind on
Jade,

You have to say /resources/package-key/file-name, so that won't be a problem.

If that file doesn't exist, we currently go look at www/package-key/file-name afterwards.

/Lars

Collapse
Posted by Andrei Popov on
Having resources under www helps fine-tuning .adp that is within www by having just a resources in href, instead of ../resources
Collapse
Posted by Dave Bauer on
Actually ../resources won't work.

The request processor will route the requests correctly if you use "/resources/"

Collapse
Posted by Alfred Werner on
A different perspective on the whole matter -
what is the best way to lay these out so that e.g. a Dreamweaver user can access the ADP files and images
without messing up the nice TCL and Database code?

Does this TIP incorporate any thinking in that direction?

As the admin of an OACS instance there are times where I open directories up to designers. Don't want to risk the whole tree.

Thoughts on my post -

perhaps presenting an inverted symlink tree for www and resources would solve it ?

e.g.

/www/myblog -> /www/instance/packages/lars-blogger/www
/resources/myblog -> /www/instance/packages/lars-blogger/resources

I think then, designers using their tools and selecting image refs from a directory structure won't get botched up...

If that works, it's feasible the package manager could create/destroy the symlinks when sitemap is used to mount packages.

This doesn't address subsites - I haven't used them so I don't know how they work.

Final thought - where do CSS files go? Looking at my HEAD from last night (a scary thought) I see css files under packages in:

/www/doc
/www

should they be more properly placed under /resources in this TIP? (ditto with .js libraries?)

Collapse
Posted by Tom Jackson on

I like the idea of /lib, when you have tcl/adp pairs. Has the /templates directory gone away? In any case what is the substructure of /lib or /templates going to be. For small packages this probably isn't an issue. Should each package make it's own internal structure? is it a copy of /www directory wise?

Collapse
Posted by Lars Pind on
For skinning and/or dishing out a copy of your tree to a graphic designer, I'm thinking we'll need some /templates directory, possible right off of the main package root. But that's not going to happen for 5.0, which is why I didn't include it here.