[TUTORIAL-DRAFT] MVC Component Development - Part 1

[ianmac]

Just a note to inform that these tutorials will no longer be maintained here as they have been moved to the developer's wiki.

Please see: http://docs.joomla.org/Developing_a_Mod ... t_-_Part_1

Ian

Please feel free to continue discussing this tutorial here.

Hello Folks,
Some of you may have seen me around, I am a member of the Developer Documentation team.  Anyway, this post is an experiment to see if we can produce documentation using a collaborative approach.  I have begun work on an outline (with some parts filled in) of a tutorial that explains how to develop components using the new MVC framework included in Joomla! 1.5.  I am going to post this outline in this thread.

Here is where all of you come in: I want your help in filling out the outline and suggesting modification and improvements so that this outline will become a tutorial which will be very useful for developers who are attempting to develop components for Joomla! 1.5 using the MVC design pattern.

How it will work: As I said, I will post the outline here.  Then, I invite you to submit responses that contain either:
a. material to go into one (or more) of the sections of the outline
b. suggestions for modifications/improvements (including how language might be used more precisely, or clarifications to portions that may be confusing, or adding detail that may have been missed), or corrections to content that is not completely (or not at all) accurate.

When I receive these responses, I will take the additions/modifications and edit them back into the original outline.  That way, as we go along, the outline will begin to unfold into the full fledged tutorial.

This is your chance to get involved in producing documentation with very little commitment - by submitting a section you are not committing to becoming a member of the doc team, you are merely contributing to this tutorial.  Anybody who submits will be listed in a credits section of the document.

Looking forward to your submissions and I thank you in advance for your assistance!
Ian

[ianmac]

Please see dev.joomla.org for the tutorial contents.

[mjaz]

See attachment for a bit about books.php and amdin.books.php . Of course, feel free to edit.

[staalanden]

Hi this sounds like a great project.

Is it possible to provide a simpel hello world example implementet in the MVC ?

[AmyStephen]

Ian and all -

This is great! I wanted to point out two possible resources for this effort (or possible points of collaboration).

A group of community members set out to do something (I think?) in building a Joomla! MVC Tutorial  . Maybe this is different or perhaps things didn't work out, but I saw this earlier this year and wanted to point it out in case it is helpful.

Also, I saw that Narcissus very recently posted an annotated reference to the weblinks component. Perhaps that might fit into this?

Thanks for your efforts here - this kind of documentation will be used many times - and the extensions produced by those developers will provide great value.

Hopefully, that was helpful? If not, my apologies.
Amy

[Chris Davenport]

Thanks for the links Amy.  The Dev Doc Team is already aware of both these contributions and we will do whatever we can to support such efforts.  Both are excellent examples of how the community can contribute to this project without necessarily entering into a long-term commitment.

I do hope that the MVCCTC project can carry on their good work.  They seem to have stalled for the moment, but I hope this thread will provide some impetus and encouragement to redouble their efforts.  I'm sure Ian will not mind if the results of this thread are adapted and incorporated into the MVCCTC wiki should they so wish.

MVC is such an important part of Joomla! 1.5 that producing good quality documentation for it is an important goal.  This thread, the MVCCTC wiki and Narcissus' annotated component will all help us achieve that goal.  So keep the ideas and the contributions coming.

Anyone not already familiar with MVC might like to read this: http://www.phpwact.org/pattern/model_view_controller.

Regards,
Chris.

[instance]

Without a detailed read, my first suggestion is that this useful link from Chris gets integrated into the tutorial itself.

Anyone not already familiar with MVC might like to read this: http://www.phpwact.org/pattern/model_view_controller.

[webamoeba]

yes we have stalled some what... I've been trying to rally the rest of the members round, but to no avail

[Chris Davenport]

@webamoeba.  Is there anything we can do to help?

Regards,
Chris.

[P_Joomla]

Hello Team:

Exist any possibility in this Tutorial to refer to the old functions and classes in the old Joomla Legacy or what in the previous Components we have that its not anymore in the new platform.

My problem is I'm trying to understand the API and learn what is the functionality of each function and class in order to develop a component. But I'm very confused. I don't know how to start. Because some functions are deprecated. I'm like looking at components inside the framework 1.5 and others that I have downloaded during the past months and it is very confusing.

This article is great and the explanation is down to earth.


Also, exist the possibility to develop more documentation about the classes and functions.

Start with Joomla! API is a little tough.

If at least exist the right explanation about the specific purpose of each class will be easier. Some code is documented but other is not.  But sometimes if the code is documented is not very clear, well it is clear for the developers in the Joomla! Team. But for people outside of that group it is more dificult. Will be a good idea to audit the comments on the code. It is part of the documentation, I think so.

For sure I know for any related with PHP will have to spend days or more to understand the whole behaviour of Joomla!.

Thanks, Team. and sorry for now I'm in the learning process.
P_Joomla

"Always is a begining and most of the time is tough"

[wojta]

Hello Guys,
I'm very impressed by joomla project and the whole joomla community.

Recently I have seen joomla 1.5 and have decided to use joomla as my web application framework. Unfortunately, there is no good example of creating joomla 1.5 component, plugin etc.
I found it very frustrating that Helloworld http://help.joomla.org/content/view/773/125/ gave me errors in patTemplate (Joomla! 1.5.0 Beta [ Khepri ] /mysq-5.0.21/php-5.1.4/Apache-2.2.2) 

Anyway, I started from the scratch and wrote my own Helloworld component. Narcissus http://forum.joomla.org/index.php/topic ... #msg672813 described weblinks component and I believe it's a great beginning. I used some of his notes in helloworld and added some my comments.


I published the component on my website http://vojtechovsky.net/joomla/componen ... de-en.html

I would like to rewrite the component  and make it compatible with the new Joomla 1.5 MVC framework as ianmac suggested for the personal library component. It might be finished this week (if i have find some time).


Could please have a look at the component and try it or add your comments. I really like to somehow contribute to the joomla community.

[ianmac]

That's great!  An MVC explanation will be helpful - everybody picks up a different aspect of the development process.

If you need help, just ask.  Also, if you get stuck as to how the MVC framework fits together, you could look at the component in the com_hello example thread at http://forum.joomla.org/index.php/topic,137470.0.html.

Ian

[P_Joomla]

Hi,

Thanks for the Hello World tutorial. Now things are doing more sense.


P_Joomla

[ianmac]

wasn't my work...  thank the originator of that thread.

Ian

[wojta]

hi ian and everybody,
I'have nearly finished a new MVC helloworld component and hope I will publish it next week(or on Friday).  Nevertheless I think I get stuck with some minor bugs in joomla! 1.5 beta1. It seems like joomla has problems with executing sql files. I went through forum and found couple of issues.

        * JInstallerComponent::install: SQL error or missing or unreadable sql file. DB function reports no errors

Warning: file_get_contents(C:\web\xampplite\htdocs\j15\administrator\components\com_helloworld\) [function.file-get-contents]: failed to open stream: Permission denied in C:\web\xampplite\htdocs\j15\libraries\joomla\installer\installer.php on line 639

Problems are solved in the latest night build so I would suggest keeping somewhere the build that worked for me and for the helloword example. I understand joomla 1.5 is beta and is still under heavy development.

Anyway I will keep all files on my website till we found some place to put them.

thank you all for encouraging emails  :-*

Wojta

[ianmac]

Well, I couldn't find your file...  actually, I found the file you mentioned before on the site you listed, but there was no SQL file in the actual zip file.  What SQL query are you using?  I couldn't think of any reason your component would have to modify the database.

The easiest place to put the component where it would be accessible to many would be to include it at the bottom of your post, as the poster on the other thread did.

The tutorial you wrote is a good one.  It doesn't really belong in development, as it is more related to administration.  If you wanted to leave a message for Michelle Bisson in the User Documentation forum (under the Documentation Workgroup section) that would be the best place for it if you would be willing to license with the creative commons license that they use (I'm not sure exactly what it is).

Anyway, great job with the component, and I hope you learned lots!
Ian

[ianmac]

Okay...  I have a question for people:

Is it more useful to continue the component/tutorial as it has been started, with a more complex component?  Or would a walkthrough of a simple (hello worldish) component be better to start, and then further tutorials that built upon it to add functionality?

i.e. Tutorial one: Hello World! (basically, a View-Controller component, without a model)
Tutorial two: Hello World! with retrieving a static hello world message from a model.
Tutorial three: Hello World! with retrieving a random hello world message from a model which retrieves the message from a database (where messages are managed in the back end)
Tutorial four: Take over the world.

Ian

[Chris Davenport]

Hi Ian,

I think a staged approach makes more sense.  Although step 4 looks a little ambitious. 

Regards,
Chris.

[wojta]

hi guys,
my point in my latest response was that you can not create a table during an installation.
I rewrite the hello component to MVC. Here I place more information
http://vojtechovsky.net/joomla/componen ... de-en.html

You can see the problem if you uncomment a sql section in the installation xml file.

My suggestion is to keep some joomal 1.5 nightly build to do complete MVC component(sql included)



wojta

[ianmac]

I haven't encountered the problem you are having, but I haven't tried the syntax (using the folder attribute) that you are using.  I will look at this when I get a chance.

Ian

[BernardG]

Wojta,

I have been looking closely at your work, as I am new to Joomla too, and want to learn 1.5 rather than 1.0x. So I downloaded and installed both your hello_world components.

There is a problem, but it might not be related to SQL. In different places, in your XML file, you have something like:
, or
In the DTD, those attributes are defined to be of the type NMTOKEN, which does not allow the forward slash....

It works in a text attribute, that is images/helloworld.png has no problem, but all the attributes with a slash does not validate, which might very well be the reason for which your SQL scripts does not install, as they all have

Now, I have no ideas how to correct this! As it seems to make a lot of sense to have forward slashes in there, the easiest fix might be for the joomla team to change the DTD, replacing NMTOKEN for PCDATA for all files and folder attributes, so that would be allowed, but this may have an unpredictable cascade of consequences (at least to me, as I don't know much ....)

I will make a local DTD to test what happens, and let you know.....

Bernard

PS- a little later.... I made changes to the DTD as I indicated above, as well as a few changes to the XML file, and everything seems to work as it should. Let me know if you want those files. 

[BernardG]

Ianmac,

Sound good, but I would suggest a few steps between step 3 and 4....

Looks to me the difficulty is always to have controllers dealing with multiple related tables. So, after an hello world selecting randomly from a  table, a slightly more complex example  involving 3 tables, for example, would be very useful, I believe.

Bernard

[ianmac]

Hmmm...  I understand your need to multiple tables, but once the world has taken over we will only need one table

Good suggestion.  Will be a bit down the road perhaps.

Ian

[Jinx]

@Bernard, thanks for the headsup on the DTD's. If you send in a changed DTD, either on the forums on as a patch on the forge we will commit it to the trunk.

[BernardG]

You're welcome, Jinx! Glad I can have a little contrib, what you'll guys are doing is great! As I never submitted anything to the forge, I am joining it to this, if it's OK.

Bernard
-ps- Added a txt extension, as I can't directly upload as dtd.

[louis.landry]

new dtd is up ... thanks

[wojta]

Hi BernardG and all,
I will reply again and again. There is no problem with the component. If you uncommented "sql" injection it works on joomla 1.5 night build. so It has been fixed already. All installer has been rewritten - and works fine in latest bild - libraries\joomla\installer\..

Neverthe less I DID tested it again and it's true
-install joomla1.5! beta - error
-install joomla 1.5! night build - success :P

For more details look at
http://forum.joomla.org/index.php/topic,73352.0.html - fandangoo  script
http://forum.joomla.org/index.php/topic,127783.0.html - lightinthedark script

If you want to test it anyway there is a component with the sql script included in xml.

thx wojta

[ianmac]

A few notes here:
the provided install file for the helloworld component does work.  Good job.

It only partially answers the question though: the intent I believe was to have the query files inside the sql folder both in the install file and in the installed system (i.e. there would be an admin/sql directory in the archive and there would be an administrator/components/com_helloworld/sql directory that would contain the sql files).  This does not happen with the provided package.

This is possible, however, and here is how:
In the XML file, use the following to specify your queries:

Code: Select all

  <install>

    <sql>

      <file driver="mysql" charset="utf8">sql/install.helloworld.sql</file>

    </sql>

  </install>

  <uninstall>

    <sql>

      <file driver="mysql" charset="utf8">sql/uninstall.helloworld.sql</file>

    </sql>

  </uninstall>

note the the folder attribute of sql has no effect, so I have removed it.  The different you will see here is in the sql file that is specified.  I have added sql/ in front of it.  The installer will look for files relative to the administrator/components/com_helloworld directory (i.e. it will look relative to the installed destination, not relative to the package root).

In your section, you might have a section that starts:

this is used to install your files.
Inside of this, add the entries:

Code: Select all

      <filename>sql/install.helloworld.sql</filename>

      <filename>sql/uninstall.helloworld.sql</filename>

The rationale:
If you add a section like:

it will copy those files into the /administrator/components/com_helloworld directory.

I hope this is clear.  I will attach the complete xml file with this post.

Ian

[BernardG]

Ianmac, and Wojta,

I will make a few more tests today to confirm, but what I believe is happening is that any XML statement which does not validate against the DTD is not executed, which would make sense....

For example does not validate, as the element sql has no provision for a folder attribute.

I use Eclipse, which point to an error on those lines. XMLSpy is great, if you can afford it.....

Bernard

[instance]

As far as I recall, the installer parser doesn't validate. If it works in the nightly build, then it works. The Beta is both horribly out of date and seriously broken. All error reports against the beta get met with "try that against the latest nightly" and otherwise ignored.

It'll work in Beta 2, when it gets released. I'm holding my breath. Well, actually, I just run from SVN.