Widgets -Where do I start?

[Michelle Cryan]

I was recently upgraded to the Enterprise Edition and was excited to begin using the widgets I had heard so much about, e.g., news pulls, photo galleries, etc. EXCEPT, there are zero pre-built widgets to dissect and figure out how to build a new one. Cue Game show loser sound effect... "WAAAH wahhh waaaaahhhh"

I get that they begin with structures, but what I don't get is how to make the variables as part of the structure and how, in the end, those would get pulled into the widget.

Here's what I'm thinking would be the end result. User wants to make a photo gallery. Adds "Widget-Photo Gallery" to their container. A pop-up window asks them to browse for a folder and voila! Photo Gallery.

If you choose to reply, Fienen and/or Falzone, type slowly so I can understand. :)

[Jody Benedict]

I am working on this exact same puzzle right now. So the answer has and audience of at least two. :)

[Michael Fienen]

I love how you call out Chris and me specifically on this, heh.

Widgets are crazy easy. I actually just finished up on one for departments to use to pull in custom listing of news from PR based on categories. It took less than an hour to set up.

If you are familiar with writing dynamic Velocity code, you pretty much won't have an issue. Let's use your case of a photo gallery (and we'll assume you're gonna use the built in gallery macro).

Create a structure with a type of widget, and call it something like "Photo Gallery." Add a text field called "Gallery Path." That's where they can put in the folder name with their pictures. Now, edit the Widget Code field, and you'll do something like this:

<h2>$widgetTitle</h2>
#photoGallery("$galleryPath")

Bam, you're done, instant widget. Now, you could start taking it further, like add fields for photo height and photo width, then set them in the widget code. That's what I usually do. When I use a widget to serve as a UI for a macro, I'll add a section at the bottom with all the optional elements you can set, and in the widget code, I see if those have been entered, and if so, add a #set() line for that macro variable.

There's also some info in the docs about how to set it up that'd probably be helpful: http://www.dotcms.org/documentation/widgets If you want some real time help, come by the IRC channel (http://www.dotcms.org/community/irc.dot) or catch me on IM or Twitter.

[Christopher Falzone]

Hah, there's my name. Michael's answer is great so I won't go much farther than saying that there should be some simple examples like this in starter site. I thought there were some, but if not, then hopefully the DotCMS guys are listening and they'll put some in. You could also stop by their JIRA and put in a request: http://jira.dotmarketing.net

[Michelle Cryan]

I think I've pretty much got it.

1. Create Structure - Make sure it is a widget structure type.
2. Add Custom Field
3. Learn Velocity
4. Insert Velocity and lucene query into Widget Code field
5. Have users add widget to pages and watch your site blossom.

I'm still a little stuck on #3.

[Jody Benedict]

yep. #3 is a doozy.

[Christopher Falzone]

So yeah, velocity is a strange animal, but as far as programming goes .. it really is not that hard.

The main concepts you need to know are
#set - sets a variable
#if ... #else ... #end - for conditionals
#foreach ... #end - for looping

Macros -- Macros are like a chuck of code that just gets executed. They cannot return a value, but they can #set a variable.

Viewtools -- Java Objects. Velocity is Java under the hood so for the most part .. whatever you can do in Java you can do in velocity.

That is really all there is too it.

1. Check out the user guide: http://velocity.apache.org/engine/devel/user-guide.html
2. TRY it .. you're never going to learn velocity unless you get your hands dirty
3. If you can't figure something out .. join us on the irc channel .. #dotcms on freenode.

Good luck :)

[Jody Benedict]

actually... I just did it in about 2 minutes. Easy. The basic bit anyway. Now I realize that I need to create some pretty css to make the gallery not look meh.