Documentation for Zii

hey, guys?

I’ve searched for documentation on how to use Zii extensions, but I couldnt find anything

Does Zii have cookbooks, documentation and real examples? I dont know for others, but at least for me, a sample is more useful than a lot of classes specifications. I’ve tried to understand the simple zii Grid extension, but I saw the parameter DataProvider for example and the documentation for the extension is not clear

I’m lost in the dark, could somebody help me please?

thanks,

regards!!!

Seriously, Yii needs a repository of examples. The api shows what fields are available, but not what options you can set. Seeing some clear examples would change everything.

Hello,

I’ve found a demo of how to use the CGridView works in the admin view / post controller of the post module in the blog demo…

But I agree that it would be nice to have some few more examples on how to use the other Zii extensions… just a few lines of code that you can try to copy and paste and it works.

There could be another small demo project called “playground” or something like this that has a few database tables just to show also how relational ar works with a single controller and one or two views that you can use as a starting point to try out on the fly code snippets that you could find on the cookbook or examples/snippets repo; so then each snippet could have a label that states “this one has been tested with the “playground” demo of yii from version 1.1.0 to 1.1.3 …” ::)

what do you think?

bye,

Giovanni.

p.s.

some of examples you can find starting from here will work on the fly.

It sounds great, Giovanni!

in reference to

"…some of examples you can find starting from here will work on the fly…"

It is a very good starting point, thanks for pointing to it!!

cheers :)

I totally agree. While I am very impressed with the level and accuracy of “straight up” API documentation available on the Yii Framework, often times a picture – or in this case an example – says a thousand words. I absolutely LOVE PHP’s documentation because not only is the API reference available, but each manual page has multiple examples of common usage. Comments from the community below each manual page also help significantly.

Unfortunately the issue is compounded by the fact that Yii’s site and forum search capabilities don’t handle relational-term or whole-phrase matching, so finding examples in the forum is often hard, too. I’ve resorted to using Google for all of my Yii searching now using “site:yiiframework.com [search terms]”.

That being said, I love Yii and think that Qiang and group have done an absolutely amazing job with it. Even without examples the docs and amount of information available is still heads and tails above many others. Keep up the great work, guys.

Sure, I also love Yii and have to send many thanks to Qiang and all Yii team…this framework is impressive…very good written, fast, easy and flexible

I hope someday we’ll have a good repository of examples to make Yii even better, because the forum is already a very good tool, however, going straight to the point with a good example is way better i think

regards! :)

Yes… about this point also Qiang made it right in fact you can comment the documentation pages of the yii documentation too.

…but another documentation I do love is the one of the YUI that provide a very extensive set of examples… for example see this ones… you click on a example, you can see the code and try a live demo.

For yii we don’t need a live demo… a offline demo we can use to copy and paste to try out the examples would be great.

We could arrange this by ourselves starting from a skeleton app if someone wants to open a google project… we could use the google code wiki and the cookbook here to publish snippets and examples and the downloadable app as a demo to try out all the code… And then if it takes shape it could be part in the future of the official release. In this way we won’t add more work to Qiang and the rest of the team and we’ll have a place where to keep organized the help that is given on the forum. What do you think?

Yeah, I totally quote this… they made an amazing job and also the current documentation is excellent… having some examples that can be tested quickly as a starting point for learning how yii works would be a plus that will make it easier for new users to get confident in doing things…

a couple of examples to explain this:

the CJuiDialog example works with just a copy and paste and show how powerful and handy Yii is for this kind of things… while the slider example gave me some visualization problems, probably related to css, that I’ll have to spend some time to investigate.

Of curse on the documentation the examples are more a complement to explain how it works, than an example that will work out of the box for each release, but imho it would be great if we could have a community based set of examples that are verified by users and kept up to date with current version of yii (and/or a specific demo released with yii like the possible "playground" one I mentioned in my prev. post).

bye,

Giovanni.

I’d love to take place in such project, the only thing I’m afraid is that I wouldn’t have too much time to spend on it…

me too… it would be nice to find another 1-2 person that would like to join… in the meantime we could open a google code project… don’t know if the name “yii playground” could be ok and/or it sounds good and it is correct in english to give the idea… anyway… once the project is open we can start putting it together and see if it takes shape. About this I was thinking that maybe it is pointless to have the examples in the wiki… would be more easy, as the user has to download the source anyway, to put the examples directly inside the code and then specify where on the code the example is and to show the snippet of code near the example result… a bit like in the jquery ui docs… (the “view source” toggle)

Then it would be great to have Qiang and someone else of the zii team that can do a check once in a while like a “supervisor” to be sure that the examples also follows what are called “best practices” or at least that they aren’t too far from them ;)

bye,

Giovanni.

Agreed!!

Guys from Yii team checking the samples would be great either!

:)

I’ve coded a prototype of it and I think that there are a couple of things that you’ll like:

  • syntaxhighlighter extension (I’m going to release this stand alone as it is more mature)

  • it takes the piece of code to show as example directly from your files

the second point is not easy to understand but in few words you call a couple of methods, one before and one after the code that does the stuffs you want to show on your page, and it takes that actual piece of code to be used inside the <pre> tag… so that if you edit the real code that works the example you don’t have to update the box with the source code too. (of course this is possible only for php files and mainly inside controller / views).

bye,

Giovanni.

very useful!! write once and update both reference and real code! :D

waiting for your work to follow the pattern and release !!

cheers!!!

Hey Guys, thanks to Giovanni (aka Virtual Darkness) for informing me of this discussion. I have been playing with Yii since November and intend to use it for at least two projects at my place of employment and possibly for a personal side-project. Ultimately, I really like what I’m getting from Yii and I want to invest in its future by making it easier for others to get going with the framework. However we want to do it, I would be happy to contribute what I can to a more comprehensive set of examples.

It doesn’t appear there’s an exact consensus as to how this should be done. I like the plug-able “playground” demo idea. Or, perhaps simply a Zii cookbook separate from the rest of Yii. One thing that occurs to me as I use things like the Jquery UI components, is that you have this ambiguous declaration in the Yii API that CJuiDialog can have an array called “options”. It’s like, gee, thanks, that explains everything. And, to an extent, it does. We just have to go back to the real jquery ui documentation and look up the options there. This seems rather crazy to me, though. Especially for this “options” parameter. It’s the most important piece of the component. Why doesn’t the Yii api, when you click on the “options” property, show you the full range of options specified in the Jquery UI docs? Furthermore, since the options shown on the Jquery UI site are for javascript and the instantiation of CJuiDialog is in php, there may need to be little clarifications made. For example, I have not yet figured out the proper way to tell my CJuiDialog what its position should be within the PHP “options” array. I, instead, have to set it with javascript before I launch.




<?php 

$this->beginWidget('zii.widgets.jui.CJuiDialog', array(

  'id'=>'addcustdialog',

  'options'=>array(

    'title'=>'Add New Customer',

    'autoOpen'=>false,

    'modal'=>true,

    //'position'=>?? //can't find right way to specify this

    'width'=>'500px',

    'buttons'=>array(

      'Add Item'=>'js:addCust',

      'Cancel'=>'js:function(){ $(this).dialog("close");}',

    ),

  ),

));

?>

<div id="addcust_content"></div>

<?php

$this->endWidget('zii.widgets.jui.CJuiDialog');

echo CHtml::link('Add Customer', '#', array('onclick'=>'loadAddCust();return false;'));	

?>


<script type="text/javascript">

function loadAddCust(){

  //ajax load content, then:

  $("#addcustdialog").dialog('option','position',[window.innerWidth/2-250,50]);

  $("#addcustdialog").dialog("open");

}

</script>



Anyways, those are my thoughts. Like I said, I am loving Yii and plan to be using it heavily over the next six months. Any contributions I can make to better documentation would be well worth my personal time (and perhaps my employer could be made to see the value of my work time to the tune of a couple hours/week going towards this… we’ll see).

In the Yii cookbook there is a single, very useful entry that I for one would like to see duplicated for other API classes:

http://www.yiiframework.com/doc/cookbook/48/

This sort of thing is very useful - is this what others would like to see too?

This sounds great! Even though my time, as for most of us, is also scarce, I’d like to participate in this project. I can clearly see the need for more examples. Not only for Zii, but also for a lot of the Yii-classes.

Regards

Johan

Hi zeugma!

Me, Jaz Manister and scoob.junior are working on the project… for not it still is on an early stage; we are defining some "patterns" like menu hierarchy and so on…

I’ve also create a “SrcCollect” class that shows the “live” code as documentation in the page of the example… so you can have the live example with the live code, and if you edit the code there is (usually) no need to update the documentation / code sample. (cause the snippet of sample code is taken directly from the php files). This doesn’t have to be optimized as the idea is that people will just download it and start playing with it on their local pc.

We’ve setup a google code project and we will open a new thread in the forum to announce it and explain the idea behind the project… in the meantime if you want to have a look: http://code.google.com/p/yiiplayground/ 8) (keep in mind: early stage hehe)

This is a collaborative project so everyone who wants to join can contact me and I’ll give svn write access (google account needed).

At the meantime the version of svn should have a clean code and try to be the near close as possible to "best practices"… so if you want also to contribute the best thing is to have a copy to play with and another one to use for commit changes. All samples should always work and be "current" with the Yii current stable release (1.1.2 at this time).

let us know what do you think ;)

Bye,

Giovanni.

Very good initiative!

Projects like these makes learning process shorten(without head aches) and more pleasant :)

A little bit OT:

Do you know how to implement a theme change in Zii Jui (e.g. Tabs)?

Previously I used very nice simple tabs in late 1.0.11 but now I can’t get it in 1.1.2, am I missing something?


<?php $this->beginWidget('system.web.widgets.CClipWidget', array('id'=>'test'));?>

<ul>

	<li>test;</li>

</ul>

<?php $this->endWidget(); ?>

Keep up the good work!

CoLT

Hello,

I’ve opened a thread dedicated to the Yii Playground project: click here ;)

bye,

Giovanni.