What about a code snippets collection resource ?

[almoravit]

Hi,

I supose that this question should be posted here. If not, please, feel free to move it where you think is the right place.

I think it could be a good help for the coders community to have a repository of code snippets. I've spend many hours looking for code examples on google, docs.joomla and even Joomla! source code to find those five code lines which, sure, every other coder has searched before.
Subjects like "Component creation tutorial" are not the target of this repository, but "Add style sheet" are more appropiated to the resource I'm thinking.
Is there something like this?
Do you think this could be a useful resource ?
It has sense to have something like this ?
Is docs.joomla the right place to host this resource ?

Thanks for your time.

[Chris Davenport]

Yes, we would very much like to encourage people to add code snippets to the documentation, particularly for the class and method pages in the API Reference (http://docs.joomla.org/Framework). Something like "Add style sheet" might be added as an example to http://docs.joomla.org/JDocument/addStyleSheet, for example. More extensive examples could be given their own pages and we can easily set up a new category to make it easier to find them.

Regards,
Chris.

[almoravit]

Hi Chris,

Would you mind to check that ? http://docs.joomla.org/JTable/getobjectslist
As it is my first document I only want to know if I'm moving on a good way. Is there any style book for documentation and any conventions for page names?

Thanks.

[Chris Davenport]

The pages in the wiki which have the names of Joomla Framework classes are effectively "reserved" for the API Reference. Sub-pages of the form <class>/<method> where <method> is a method of the Framework class called <class> are also reserved for the same reason. At the present time I think it's best not to add any sub-pages beneath a class page that are not method pages.

It could be added as an example to this page: http://docs.joomla.org/index.php?title= ... &redlink=1 which doesn't exist yet. This is part of the API Reference and you should read these guidelines if you want to add a page there: http://docs.joomla.org/API_Reference_Project

A good example of adding an example code snippet to an API Reference page is: http://docs.joomla.org/JDocument/addScriptDeclaration

You might also like to read this page: http://docs.joomla.org/How_to_use_the_d ... our_script which includes an example similar to yours and is a more task-orientated page.

It is also possible to create a separate code snippets area and I'm open to suggestions on how that might be organised.

Regards,
Chris.

[almoravit]

Hi,

I was a litle busy this days, sorry for delay. Thanks your suggestions and links. As far as I've read they I'm sure will help me!
A separate area for code snippets could be nice. As they are more a cooking receipt, then it could be nice to have links in the <class>/<method> document with several code snippets.
To help readers to find code snippets could be usefull to add a 'Code snippets' title anywhere (pe, after 'See also' paragraph ) in the <class>/<method> document, in the <class> document or even both. This allows to share code snippets with different <class>/<method> and <class> because one code snippet could involve several classes and several methods.

Best regards,

[Chris Davenport]

Here's a suggestion that would make the code snippets easier to find and maintain...

When creating a new code snippet, give it a sensible, descriptive title. No need to include "Code snippet" or anything similar in the title. Instead, add [[Category:Code snippets]] to the end of the page, together with other relevant categories. In particular, add a [[Category:JClass]] and [[Category:JMethod]] for each class and method used.

Then, in the JClass page, add a Code Snippets section with the following code:

Code: Select all

<dpl>
  category=Code snippets
  category=JClass
<dpl>

for a class page, or

Code: Select all

<dpl>
  category=Code snippets
  category=JMethod
</dpl>

for a method page.

The code snippets lists will then be generated automatically.

Chris.

[daverii]

I am sure that Chris knows about this but I had a similar requirement although I did not know about this thread.

I found the same tool and this page describes how to get various kinds of Category list.

I was looking for a way of controlling the size/appearance/relevance of the list so that my page design stayed reasonably balanced.

Time will tell but this seems to be the man for the job.

[almoravit]

Hi,

Nice suggestions Chris!...
I we'll play with it the sandbox first...

Good link daverii. Will be useful!

Thanks!