Thorsten Scherler wrote:
El lun, 16-01-2006 a las 17:05 +0100, Gavin (JIRA) escribió:
...
Example :
In the search contract - which is used twice in the pelt theme (as locations
examples), the getBlank.js file is, also, included twice.
<forrest:content>
<forrest:part xpath="/html/head">
<script type="text/javascript" language="javascript"
src="{$root}themes/getBlank.js"> </script>
</forrest:part>
...
</forrest:content>
gives :
<script language="javascript" src="../themes/getBlank.js" type="text/javascript">
</script>
<script language="javascript" src="../themes/getBlank.js" type="text/javascript">
</script>
in the head part.
The getBlank.js can be used in any given form. It states in getBlank.js:
" * getBlank script - when included in a html file and called from a
form text field, will set the value of this field to "" if the text
value is still the standard value.
* getPrompt script - when included in a html file and called from a
form text field, will set the value of this field to the prompt if the
text value is empty."
To extract it to its own contract makes perfect sense since you would
control in the structurer that it is included just once.
Like I never get tiered to say:
"Contracts used in the dispatcher are standalone, self explaining,
configurable pieces of xsl templates, created out of pure maintenance
reasons."
We have heaps undocumented code in our code base, the dispatcher tries
to encapsulate this code in functional code bits and allows us to
document within the same file. We focus on devs right now and IMO devs
are looking into the code for documentation (especially in open
source).
The getBlank.js is providing the documentation in the code but not where
it finally used. That forces a contract author to open the jscript and
reading the head. IMO it makes more sense to document it in a contract
where I can then lookup via ls.contracts what it is doing and how I can
I use it.
WDYT?
I'm +1 for this, but...
The documentation generated by ls.contracts is not sufficient. As the
number of contracts grow it is going to get increasingly confusing.
Don't get me wrong, I totally agree that ls.contracts is a massive
improvement over what we currently have, I just want to flag up that we
can improve much more.
I think that (at some stage, not now lets finish what we started first).
We need to consider "types" or "groups" of contract. This will allow us
to separate those contracts into logical collections, both for
distribution and for documentation.
So, for example, the above getBlank.js is, most likely belongs to a
"forms" group. How these groups are identified, grouped and distributed
needs careful consideration (at some point in the future).
Ross
