Simple website : I am lost

Hello.

I am just starting with MODx. My purpose is to create a personal web site, but, as a first step, I am creating a very simple web site for my research group (I work at the University as a lecturer).

In fact, it is such an easy site that I could have done it just with notepad+HTML+CSS. But I thought it would be a good opportunity for learning MODx.

First of all, I said "learning MODx" in the same sense you say "learning C++" or "learning Phyton". For me, it’s like programming, sometimes. And I like programming, but... I am lost.

I am not going to say that there is not documentation for MODx. But I can’t get used to the existing documentation. I don’t get the point.

I am at this stage:

- I installed MODx without any trouble.
- I followed the Beginner’s guide from MODx-Wiki (http://wiki.modxcms.com/index.php/Beginner%27s_Guide_to_MODx). I found it very useful. I used it together with the basic documentation at MODx site.
- I have also created an appropriate HTML template for the site I’m trying to build, and the associated CSS file. I’ve put them on my MODx system.
- I have managed to publish one single page. Hurray!!
- I understand what "Wayfinder" is and how to use it. Also, I liked "Breadcrumbs" a lot.
- I think I understand the difference between snippets, chunks, etc.

But:

- I have slightly understand all the features and possibilities that Ditto, Reflect and other snippets can provide me. But I don’t know exactly how to use them, how to get all the profit from them.
- In fact, I don’t get the idea of what a Template Variable, a snippet, a placeholder IS and IS NOT (I’ll explain this sentence later in this post).
- I don’t know what to do in order to bring the web site from my mind (and my traditional notebook) to my MODx system.

This is what I have in mind:

- A presentation page (that would be the initial page).
- A "members" section, with one single page for each member of the research group (with contact information and so on), and one main page for this section, where you can access to each members page, just like a blog page, where you see the "intro" text for each "post". I guess that Ditto should be used for this.
- A "research" section. Two sub-sections:
- Research lines: just a web page with a list of our research topics.
- Publications: a clickable list with all the papers published by us. Again, I guess that list should be done with Ditto or something related with.
- A contact page: typical contact form.
- That’s the most important. I want also to have a "search" button in the sidebar.

I am going to explain my problem, where I think I am getting lost.

When I think of a list of publications (a dataset, in fact, with a normal structure: author, title, publisher, year, etc.), I DO KNOW that Ditto should be used, but I don’t know how to use it. Also, I don’t know if it is as easy as adding "[!Ditto... ... ...!]" somewhere in my template, or if I should also use a "template variable" to show the results (the clickable list of all the items, I mean), or if the most appropriate is a "placeholder", or whatever... I get lost, because I don’t know which is the next step, and I don’t understand the "philosophy", I think.

As fas as I know, TV are for showing content. But also Snippets can show dynamic content. Or not?

Maybe I need a slide with a "box" for TV, Snnipet, "placeholders", and some rows showing the relationships between them.

Also: can I use the same HTML template (Resources > Templates) for all the site, of should I use a different template for the pages that act as the "main" page of a list ("members" page and "publications" list page)?

I would accept reading all the documentation you told me to read, but the more I read, the more confused I get, because I don’t know how to put it into practice.

Sorry if you think I am too lazy or silly... I think I need some kind of hint, some words like "It is all about..." or "It is just like..." or "Try this...".

Thank you in advance.

Here’s something that might be helpful (more later):

TVs are just additional custom content fields. They can be as simple as a text field, or they can be more complex like an additional Rich Text Editor instance or set of Radio Buttons/Checkboxes or a drop down list. That’s MODx TVs 101.

The cool thing is you can get a PHd in TVs, too. That’s where @BINDINGs come in. Here’s a peek at TVs 301:

Consider the following situation and document hierarchy:

Home (1)
Staff (2)
  Jane
  Steve
  Jim
  Sally
About (3)
  Company
  Contact
  Directions

Now make a new TV [*section*]. This can be used for a variety of things (like for holding the contents of a sidebar found on every page, or for adding additional Javascript or CSS to the header of individual documents or sections of your site), but for this case we’ll use it to add a simple word to the top of every page in your template:


When you define this TV, do a couple of things:
1) Make sure you assign it to every template you want to have access to it
2) Assign a default value to it: @INHERIT Staff

@INHERIT is a TV trick I use on almost every site. Basically it makes the TV behave as follows in the above example:
[*] If you explicitly insert a value, use that. In your About section you’d want it to say "About". On the home page, you might want "Welcome".
[*] If you don’t input anything, it’s going to use the value "Staff", based on the assumption that you’ll be adding more staff than anything, and you can skip data entry for that TV in that instance.
[*] If you change the value of it in About (3), all the child docs contained by 3 will first look to see if there’s an override value in their local copy (see the first bullet here), then start traversing up the document tree to look in parent/ancestor containers to find a non-default/overriding value. When it finds one it uses that. If it doesn’t it falls back to the default value (Staff)

Another good use of TVs is for the aforementioned adding of extra Javascript to document headers. With all the Ajax libraries and code snippets floating about that frequently conflict but that require adding things to your web pages in the HTML head section, it’s tempting to use them on different pages of your site. Add this to your template:


Define your TV [*extra-head*] as a Textarea mini with no default value and assign it to all your templates. This way you can limit the number of templates you need to create so you maintaining your site can be more simple. If you need a jQuery script on one page and a Mootools one on another page, just add the relevant extra bits to those specific pages and you’re done.   

Hi GinerBosk. Welcome to MODx

Well, if you like programming, you know that there are always several ways to do things. Some might be "best practice", others give you the best performance, etc. But there is no right or wrong. Same goes for MODx.

Some people might use Template Variables for all kind of stuff. Others might skip the entirely.
Here is how i use the tools MODx provides:

Templates
The base site template. You can get through with just one template, but since Template-Variables can be defined on a "Template-Basis" i normally create different templates for different Template-Variable needs. In your case i’d create a special template for the "Publications" since you can then add Template-Variables for the different content like: author, title, publisher, year ... Using these Template-Variables in other Documents is useless, thus you bind them only to a specific "Publications-Template". For all the html code that remains the same across different templates (eg. header, footer etc.) i use chunks.

Template-Variables
Basically all content that you might want to add in addition to the normal Text-Content of a document. Provides some great functionality like @BINDINGS and predefined input and output "widgets".

Chunks
Look at it as they were global constants . Well, thats not entirely true, since you can also write Chunks, but i mostly use them for static read-only content i use in several places. Like some HTML Code (Header, Footer...), Placeholders that will be filled by snippets etc.

Snippets
Snippets are - as you might have read - small bits of PHP Code that provide extra functionality. Some of them are quite powerful and complex (Ditto, MaxiGallery, ...), some of them are dead simple (for example you could create a snippet that returns a specific chunk-content based on a language-variable). You can add parameters to Snippets and create highly customizable extensions.

Plugins
In my book, snippets are used for the frontend, plugins for the backend. The great thing about Plugins is, that you can bind them to events. So you could write data to some DB whenever a user saves a document... basically this is the point to extend your backend-functionality.

In practice one can create a huge mashup of all these techniques
Snippet call in Template-Variable, Template-Variable accessing a Chunk, Plugin writing a Chunk.. etc.

To create a contact-form, use the eForm Snippet. It has a great documentation too.
You can use Ditto for all sort of stuff. Basically you use it to summarize documents or display sorted document contents etc.
A good application of the Ditto snippet would be your Publications list:
Create a Document-Container that holds all your Publication Documents.
You can then place a Ditto call in the mentioned Document-Container that will summarize all Child-Documents and even output them sorted by your "year" TV.

Hope that helps a bit.
Like i said: there are different ways to accomplish things. Just give it a try.

To banal and rtharash,

Thank you for your suggestions and hints. I found them very helpful.

I guess MODx is very powerful and I accept that you have to write some code and there is not just one way to do things...

My problem with MODx is (in programming terms): How can I get from a "Hello World!" program to a more sophisticated application?

I am thinking about changing to another CMS like TextPattern, but I still don’t want to —I see MODx as a challenge and a "perfect" tool, if you succeed in managing it. I "believe" in MODx.

In the practice, I have TV, I have PHd, Snippets... At the beginning, it’s is difficult to imagine what they are really for, and how to use them (or which is the best way to use them), as other CMS don’t have such a variety of "elements" (as fas as I know).

Banal, the examples you gave me are quite useful. By the way, you mention your "book". Have you written a book about MODx?

Thank you again.

More answers will be welcomed.

Quote from: GinerBosk at Jan 25, 2008, 04:01 AM

Banal, the examples you gave me are quite useful. By the way, you mention your "book". Have you written a book about MODx?

I’m afraid no, i have never written a book . Its just a figure of speak.
It seems like you have your "Hello World" application allready. You did create a document successfully and used Breadcrumbs as well as Wayfinder. Thats a good start.
All Snippets work basically the same in terms of how they are called and how parameters are passed to them. What the parameters are is somewhat a problem, because there is no standard to it. You have to find a good documentation for them... some of them are very good, some are rather bad or non-existent (i had to look at the source of some snippets to figure out what they were doing).

As i said. There is no best way.. there are always different possibilities. I encourage you to do some test (maybe on a local installation) to figure out what works best for you. It’s not that you can’t "undo" a choice. If you find something too cumbersome to handle, try another approach.

My problem with MODx is (in programming terms): How can I get from a "Hello World!" program to a more sophisticated application?

How sophisticated are you talking about? In any case you will need to use snippets to get anything more sophisticated. A snippet is basically php code that will be executed on a particular document. You can use the MODx API functions to help out with MODx specific stuff as well as database connections and other useful tools.

In most websites there are a handful of existing snippets that you will most likely use. In general these relate to modx documents and use the document structure in their output (Wayfinder for menus, Ditto for displaying documents, ajaxsearch for document searching, etc...). Then you can build custom snippets that can do whatever logic you want.

Some snippets have their own support sites:
Ditto: http://ditto.modxcms.com/
Wayfinder: http://www.muddydogpaws.com/development/wayfinder/features.html

Some others have documentation in the Wiki:
http://wiki.modxcms.com/index.php/Category:Snippets

Another good place to look is in the actual snippet code or in the assets/snippets/snippetname/docs folder.

Snippets are easy to put together (if you know a bit of php that is), here is a good tutorial with some tips and examples:
http://wiki.modxcms.com/index.php/Creating_Snippets

I know this may be an obvious question but did you install MODx with the default Dataset? This installs examples of snippets with chunks and much of what you may want to accomplish with your site. I always keep an installed version of this on my local server for playing with and experimenting and for digging into how someone else did it.

If you haven’t you should.

Sounds like you are well on your way.

Cheers,

Jay

Giner,

This is what I would do:

1. Create the the pages mentioned in your first post (leave members and research blank):
- presentation, members, research, contact

2. Right-click on the Members page (in the tree) and choose ’Create document here’
- do this for each of your members (leave the content blank)

3. Do the same thing for Research
- create a document here for both ’Research Lines’ and ’Publications’ (leave both blank)

4. Now fill in the content for the site.
- put in text for the presentation page
- For each member ’blog’, ’Research Line’, and ’Publication’, click ’create a document here’ in their respective page you made above
- for the contact page, follow the eForm tutorial at http://wiki.modxcms.com/index.php/EForm

5. Now that you’ve got content you can Start using Ditto
- remember Members, Research, ’Research Line’, and ’Publication’ were all left blank

6a. Example - Research Lines
- Create a new chunk called ’tpl_Research_Lines’
- paste the following code into it


6b. Paste the ditto call into the main Research Lines page (it was empty)
- if the ’Research Lines’ page ’id’ is 20, then in the parent/main ’Research Lines’ page you would put the following:



You would follow the same pattern for the other ’content aggregations’- Members, Research, ’Research Line’, and ’Publication’.
* You can use the same template for all of your ditto calls or you can create a different ditto Tpl for each one.
* Once you get this going, it really helped me and might you to go through the Tagged Ditto tutorial/walk-through on the Wiki (http://wiki.modxcms.com/index.php/Tagged_blogging_with_Ditto)

Just a little follow-up post, in order to tell you that I am keeping on building my web site —with MODx, of course. And it was possible only with your help, because when I began this thread, I was thinking of giving up. I didn’t understand anything about TV, snippets, etc., and now everything is starting to make sense.

Very soon, I am going to start asking new questions (if they’re not already solved at forums), so be prepared!

Thank you again to all of you. All your comments were very helpful.

Giner,

If you found any little tips from your experience, please paste them here or on the Wiki Beginners Section. It is really good to have a new-eyes experience for us that have been at it for awhile.

Chuck