A Newby: my observations/challenges so far...

[Guest]

Welcome, Guest. Please login or register.
Did you miss your activation email?

1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[ChuckTrukk]

My try at explaining:
- placeholder
- Template Variable (which is a placeholder)
- chunk
- snippet
- and how they work together?


Placeholder
Placeholders are like dynamic pieces of a website. In Joomla, you may have a module that says "Hello username" where username is the logged in persons username. But in Joomla, you have no control of the output without hacking the actual php. In MODx, you can create your html output however you want and use a placeholder as the 'puzzle-piece'. 2 Examples:

Code:

//Example 1
<h1>Hello [+username+]</h1>

//Example 2
<div class="welcome-user">Hello <span>[+username+]</div>

The power of the above code is you did not have to 'hack' or modify the php that creates the placeholder. Most website clients want a unique and customized look to their site. Placeholders allow developers to create dynamic output (username) but allow you the designer to control the html and how it looks. Placeholders are usually put in 'chunks' (explained later). Most snippets document the placeholders available. When you first use a snippet, you may want to use all of the available placeholders to see what is available to you.

Template Variable (ie TV)
TV's are two things. (1) They are placeholders. (2) They are extra input options. The problems with CMS' like Joomla is sometimes your user needs more than 1 content field. What if the site owner needs 3 fields- Author, Web Link to Amazon, and email. In Joomla, the user could put that information in the 1 content box and format it the way they want. Or you could teach the user how to format the information the way they want (it's a hassle to show most people how to create a table or nested div with TinyMCE). But the power of MODx is you can create additional TV's (or input boxes). How to style the output (examples below):

Code:

//Example 1
<h1>[*author*]</h1>
<p>Web Site: [*website*]</p>
<p>Email: [*email*]</p>

//Example 2
<table class="books">
<tr>
<th>Author</th>
<th>Website</th>
<th>Email</th>
</tr>
<tr>
<td class="author">[*author*]</td>
<td class="website">[*website*]</td>
<td class="email">[*email*]</td>
</tr>
</table>

The power in the above code is the user does not have to know any of the html code. They just fill in their separate input text boxes, and the TVs are placed in their placeholders. TV's offer a lot of extra options, but this is the basics.

Chunk
A chunk is html that will be shown in a document. There are many reasons to place the html output somewhere other than the main content box. 1 reason would be html that will be used in multiple pages (like a menu, header, or footer). Another reason would be to use placeholders. If we use the above example, you could put that html in a chunk so the user could not edit it and mess up the table. Let's create a new chunk called 'Books' and call it to be shown in the main content.

Code:

<!-- New chunk called Books -->
<table class="books">
<tr>
<th>Author</th>
<th>Website</th>
<th>Email</th>
</tr>
<tr>
<td class="author">[*author*]</td>
<td class="website">[*website*]</td>
<td class="email">[*email*]</td>
</tr>
</table>

Code:

<!-- in the main content of MODx, show the above chunk 'Books' -->
{{Books}}

Now the user only sees the chunk {{Books}}, but the html output is the table we created that is populated with the TV placeholders. And if the user wants to add an image or more description above or below the 'Books' chunk, they can.

Snippet
A snippet is a piece of php code that creates the dynamic part of a placeholder. If we use the first example above, the snippet would be responsible for getting the username of the user and sending that to the placeholder [+username+]. In MODx, snippets are php functions and classes. They are what make MODx dynamic. I dont know what else to put here, because snippets can be anything you can think of. They are like modules or components in Joomla.

How it all works together
(1) Snippets do the php magic- calculations, query the database, massage data. They send the final output to placeholders.
(2) Chunks hold html output. You can call your placeholders here.
(3) Placeholders are where the output will be shown
(4) TV's are simple placeholders. They also provide simple input forms (in the manager) when you just need more input boxes.


Rough draft one - chunk
PS - will anyone actually read this if it's posted to the wiki, etc?

[markg]

Pro,

Mark, how would you describe the following to an eighth grader:
- chunk
- placeholder
- Template Variable (which is a placeholder)
- snippet
- and how they work together?

I would use diagrams, pictures and lots of coloured crayons, but not too many words.

Seriously, I used to teach uni students and adults accelerated learning skills and this is one of the types of methods we used.

Actually, I was hoping the eighth grader could teach me.

[ganeshXL]

hmm, actually, I think the Books-example chunk is a bit misleading.

Syntax for placeholder = [+foo+]
Syntax for template variable = [*foo*]

The example should be:

Code:

<td class="author">[*author*]</td>
<td class="website">[*website*]</td>
<td class="email">[*email*]</td>

[ChuckTrukk]

thanks ganesh,

i fixed it. That could be a source of confusion- TVs are called [*tvhere*] and placeholders are called [+placeholderhere+], but i guess thats just something people have to figure out.

[s9]

This is generating some great discussion and ProWebscape, I would read what you wrote.  Its exactly the kind of thing someone like me would be looking for.

There is, however,  a great deal of help and gems buried within the forums, but as you've noted you have to trawl through it.

I've resorted to reading from start to finish any post and thread that is close to what I'm trying to figure out. Usually there will be something buried in there that's what I need, but it's a time consuming and tedious process. Sometimes covering dozens of pages.

What we need is some way of taking all those buried nuggets and putting them somewhere that's cohesive and organised. I don't think the wiki is the  way to do it, at least not in it's current state. And books are always outdated before they are even printed. Anyone got any other suggestions on how the rest of us can contribute to some group developed documentation area or site? Given we are all in the online world some sort of dynamic documentation should be possible.

The other thing to realise is that people have different learning styles.

Telling people to read the documentation is only to going to work for a quarter of the population. The other 75%  will need something else.

Such as visuals and graphics. "A picture is worth a thousand words" Often one good graphic can communicate in an instant more than a thousand word tute ever could.

Other people need examples, or just need to see something working to get it.

EG Telling people battling with Wayfinder to "Just install the "accordion" example from the wiki or one of Muddydogpaws examples and you'll get it, " is not going to work if they can't get them to work in the first place.

Mark, you're right on with all of this.  Really totally on track with it.


I want to suggest something for this question.  Not that I necessarily have the right answer or best answer, but, lets see where it goes.

What we need is some way of taking all those buried nuggets and putting them somewhere that's cohesive and organised. I don't think the wiki is the  way to do it, at least not in it's current state. And books are always outdated before they are even printed. Anyone got any other suggestions on how the rest of us can contribute to some group developed documentation area or site?

1)  I'd like to gather a team of people who would like to be part of writing/organizing the new docs.


2)  I think the first decision would be what kind of framework to use.  Maybe a new wiki.  I think the wiki we have now is great - but - I think we need a clean sheet of paper.  I would bet that a high percentage of whats on the current wiki would come over to the new one, but maybe in a different form or order.  It would be easiest to start with something new.  Whatever framework we use, even if it is a wiki, it would have to support videos and screenshots.  I think some kind of existing platform that uses rich text would be the best choice, I mean, we don't want to have to reinvent the wheel with that, we need something stable and intuitive so our work is easier.   Navigation and table of contents/sitemap/index kind of functions are key.


3)  This is an idea I got from the CouchSurfing group.  (I haven't couchsurfed anywhere yet, but I like the idea.)  They have these "collaboratives" which are in-person meetings in some cool place, that last anywhere from a week to a month.  Its an intensive.  A small group of volunteers signs up to do them, and then they focus intently on whatever goal they have set out for the collaborative.  They do strategic planning for the website and the community. 


I'm not suggesting an in-person intensive, although god knows, if we all had the resources (time and money) to meet that way, it would be a blast.  What I'm suggesting is lets each work from where we are, but lets maybe pick a period of time, say, (this is off the top of my head) the first 2 weeks of July.  And during those 2 weeks whoever is interested would just get as much done on the new docs as possible.  We would have a common goal and a "due date" to focus on.  It would have to start with an online chat or conference call where the basic parameters of the project and roles would be set out.  It would be some work for sure, but, it would undoubtedly get results. 


Again I'm not suggesting anyone put aside their lives for this - just if one is interested, they can set their own limits about how much time they want to give.  But, if I can be of help by organizing, or guiding, or editing... thats probably how I could best be of service to this project.


Is this a good idea?  Is it practical?


John

[OpenGeek]

John:

These are all desires of the MODx Team, and great ideas.  Let's see if we can't get all you folks that want to help improve the documentation for MODx involved in the official contribution channels...

1)  I'd like to gather a team of people who would like to be part of writing/organizing the new docs.

This is the purpose of the MODx Team, though the documentation group has been less active than we would like for sure.  If you have things to contribute, please solicit us to join the MODx Team, and you can spend as much time as you want/can helping out.  We ask people to join when we have time, typically after noticing some quality contributions from the forums and/or the community wiki, but don't be shy, please!  We need contributors.

2)  I think the first decision would be what kind of framework to use.  Maybe a new wiki.  I think the wiki we have now is great - but - I think we need a clean sheet of paper.  I would bet that a high percentage of whats on the current wiki would come over to the new one, but maybe in a different form or order.  It would be easiest to start with something new.  Whatever framework we use, even if it is a wiki, it would have to support videos and screenshots.  I think some kind of existing platform that uses rich text would be the best choice, I mean, we don't want to have to reinvent the wheel with that, we need something stable and intuitive so our work is easier.   Navigation and table of contents/sitemap/index kind of functions are key.

MODx development and documentation is being supported by a new full stack of Atlassian tools, which includes JIRA for bug tracking, a Confluence wiki, as well as Fisheye for Subversion Changeset viewing and Crucible for Peer Code Reviews.  Sign up for an account at http://svn.modxcms.com/jira/ and start participating.  MODx Team members are provided access rights to contribute in various ways, be it Subversion commit rights, wiki publishing rights, or rights to moderate a code review in Crucible.

3)  This is an idea I got from the CouchSurfing group.  (I haven't couchsurfed anywhere yet, but I like the idea.)  They have these "collaboratives" which are in-person meetings in some cool place, that last anywhere from a week to a month.  Its an intensive.  A small group of volunteers signs up to do them, and then they focus intently on whatever goal they have set out for the collaborative.  They do strategic planning for the website and the community. 

I'm not suggesting an in-person intensive, although god knows, if we all had the resources (time and money) to meet that way, it would be a blast.  What I'm suggesting is lets each work from where we are, but lets maybe pick a period of time, say, (this is off the top of my head) the first 2 weeks of July.  And during those 2 weeks whoever is interested would just get as much done on the new docs as possible.  We would have a common goal and a "due date" to focus on.  It would have to start with an online chat or conference call where the basic parameters of the project and roles would be set out.  It would be some work for sure, but, it would undoubtedly get results. 

Again I'm not suggesting anyone put aside their lives for this - just if one is interested, they can set their own limits about how much time they want to give.  But, if I can be of help by organizing, or guiding, or editing... thats probably how I could best be of service to this project.

We'd love to eventually have meet-ups, but the primary goal for the MODx Team here is to craft documentation for the upcoming 0.9.7 release so it does not suffer from all the same issues out of the gate.  We just need more volunteers to get actively involved in the documentation efforts.  Hint, hint...

As far as 0.9.6 is concerned, the existing community wiki allows anyone, not just team members, to contribute tips, tricks and tutorials already.  With this in mind, I do not see the point in expending more core team effort on the legacy releases, but I'm certainly not going to resist any organized efforts to improve the community wiki for the legacy users that will be around for some time to come, even once 0.9.7 is released.

We have an IRC channel for intensive communications as well (join #modx at freenode), and the core team members typically communicate via instant messenger when questions or other collaboration is required.

Cheers,

Jason

[markg]

Jason,

if 0.9.7 is coming, then rewriting and coordinating the current documentation may well be a redundant exercise.

While I have been one of those critical of the lack of clear documentation for newbies, I have found the people in the forums to be very helpful with whatever dumb questions I ask. Plus It's been less than two weeks since I installed MODx and I've had most of my pressing questions answered.

Maybe we should just tell all newbies to ask their questions in the forums until the new version comes out. Any time frame on when that will be?

The other thing I've noticed is that most of my queries relate to the installation and basic setup of external modules, snippets and plugins contributed by others, and not MODx itself.  That implies that snippet developers could/ should spend a bit more effort on these instructions.

As far as the Documentation Team goes, I'm happy to help out there. In my day job I'm a business communications consultant (marketing, advertising, training etc) and I've been involved in ecommerce since 1998.  So if you want a writer's eye and communicator's insight to go over anything just pm me.

[s9]

Sounds good Jason... so the new 0.9.7 will be basically a clean/fresh start for documentation.  That is great. 

So Mark is probably right that spending a lot of effort on the existing docs wouldn't be such a good idea, and we'll just all have to be patient in the interim.  I agree with Mark that forum users are incredibly supportive.  Without clearly navigable docs where the newbie questions and answers can easily be found, there's always the danger that newbies will be too intimidated to ask all the questions they wish to, that they'll give up if they're not tenacious, and that patience from the advanced forum users will wear thin.  That's known already, I'm sure, and with that statement I'm just repeating the need.

With the new docs, I'm willing to help too.  But... Jira and the other developer tools you mentioned... those don't interface with me very well.  Wikis, how-tos, and user docs in plain English is where I can be useful, but, looking at the extensive tools you have on the svn page gives me the same headache as a lot of the existing MODx docs.  If there's an official communication channel that is more on my level I'll be glad to participate any way I can.

I'm supportive but just don't know what kind of role you would want me to have.

One idea is that the more technically advanced team would have to do the initial writing.  But, they could hand their first draft docs over to a second team comprised of less technical writers/editors.  Then, after we work through it and rewrite and revise, we would have some discussions back and forth between the 2 teams, asking questions, clarifying, and so on.  It would almost be like an interview session, where we fill in any gaps of understanding that need to be filled or clarified.  And, then we could beta test the docs on people who are even less technically inclined than we are, such as business people or people just wanting to make a quick site. 

So, it would be a real team effort with contributions from people of all ability levels.

John

[splittingred]

With the new docs, I'm willing to help too.  But... Jira and the other developer tools you mentioned... those don't interface with me very well.  Wikis, how-tos, and user docs in plain English is where I can be useful, but, looking at the extensive tools you have on the svn page gives me the same headache as a lot of the existing MODx docs.

The Confluence Wiki is a pretty simple Wiki - I feel MediaWiki is much more difficult. You can find the 097 docs (in vast need of contributors!) at:
http://svn.modxcms.com/docs/display/MODx097/MODx+0.9.7

If there's an official communication channel that is more on my level I'll be glad to participate any way I can.

Most of us communicate either via these forms or in IRC at irc.freenode.net, on the channel #modx.

I'm supportive but just don't know what kind of role you would want me to have.

We want any contributors of documentation. We want testers and bug submitters for 0.9.7.

Thanks John.

-shaun

[smashingred]

Don't avoid adding documentation for 0.9.6 because while there is much different about 0.9.7 there is much the same or very similar.

Personally, I' plan to put up some screencasts and videos demonstrating how-tos in MODx.

Many people [claim they] don't get anything from screencasts but many of us do better with visual demonstrations, pictures, screencaps and flowcharts rather than text only documentation.

I have learned subjects from Acoustics to HTML to Graphic design to PHP using images, video and charts. Obviously notes, text documentation etc. is necessary but not isolated. The reason many people do mind mapping is that imagery can bring significant clarity to ones ideas and thoughts. WIkis are often devoid of valuable images and this is a shame. My favourite web design and programming books and even Tony Buzan's Ultimate Book of Mind Maps are jammed with demonstrative examples.

People make fun of the Ruby on Rails screencasts as a silly waste that shows nothing but what it did for me was give me insight into process, actions, format, syntax; a starting point. While I don't use RoR, one 10 minute video gave me way more insight into its use in application development than a 5page step-by-step howto becuse howtos don't have the dimension. A screencast can efficiently tie together several related elements all while concentrating on the one vs. constantly interrupting flow with "By the way while you do this you can...".

Anyway, Confluence is really easy to use and has an RTE that converts to wiki markup quite nicely and as splittingred mentions it is easier than Mediawiki markup; I'd agree.

Cheers,

Jay

[s9]

Great.  Thanks Shaun and Jay for the guidance. 

John

[s9]

I just found the Wanted page on the Wiki:

http://wiki.modxcms.com/index.php/Wanted


And also, one of my favorite software products, FoxyCart, just redid some parts of their Wiki.
I might like to do something similar for our current wiki.

Here is what they did:

http://wiki.foxycart.com/integration
http://wiki.foxycart.com/

I was thinking of making a wiki page that has links to all the good sources of information whether they be deeply buried forum posts, wiki pages, or off site guides (like Bob's Guides).   It would basically be a list of everywhere I went to find the information I needed to build knowledge.

[smashingred]

John,

You seem to be doing a lot of thinking on this. Personally, I hate the clutter of Mediawiki. It is made for the editors but not content seekers.

The FoxyCart stuff seems to be very well organized and thought out. I think that a simpler organization of the existing wiki is great. I don't think that enough people use the wiki myself included. Writing documentation in Mediawiki is annoying. For others it is intimidating. If you want to go in and start moving stuff, improving stuff and adding, please go for it.

One thing the MODx wiki will not be (as far as I know) is the official documentation for MODx. It will be user tips, howtos and user contributed/edited documentation. Official documentation may take elements from the wiki but there must be editorial direction for a good user guide.

It may almost be worth it to put a challenge out to post articles, edit/update existing ones and clean house. I think many people don't get wikis and don't take charge and make changes when they could easily.

On your suggestion on the Forum Gems: It would make more sense to pull the information out of the forums and into an edited form in the wiki because references are far easier to do when you don't have to jump from format to another. Links are fine for external references but for forum content I'd say migrate it.

Back to you soon.

Cheers,

Jay

[Gav]

Max, Pro, S9 etal,

I'd like to thank all of you for generating a very interesing and useful discussion.

I am a complete newbie to MODx. I know a reasonable amount of HTML, CSS, PHP and MySQL, so I can write dynamic web pages by hand OK. I installed MODx pretty easily, as there are good instructions for that. However the next step has me feeling like an idiot: I can't even find out how to change my homepage and create the very basics of a new website from scratch. If you folks plan to create straightforward documentation/examples of how to get started from this early stage, then I would be very grateful.

I would love to help out in this, as I see it as a very worthwhile exercise (I have had the same experience with many other software systems). However, I am a newbie. So if it is useful I would be happy to offer my services as a guinea pig and test any draft instructions for you. I can provide complete and honest feedback on what helps me and what doesn't.

The context for this is that I have to migrate a relatively small website (8 pages and a contact form) from asp to MODx. I have converted all but the contact form to PHP as an initial step. The hard bit is now breaking it up into templates and creating variables. Then enlisting a form snippet (?) to take over from the asp form.

And I have only 3 days to do it. All feels very daunting right now!

If you can help me with these simple steps I'd be very grateful.

And if I can help you guys in return as a 'test pupil' then please let me know.

Cheers,

Gav

[dev_cw]

MODx is very flexible, so the "best" approach will be dictated by the circumstances. The very basic steps are:

1) create the working html file;
2) copy the html into a MODx template (Resources > Manage Resources Templates tab) - note: make sure you change the file paths to the correct locations;
3) replace html tags with document variable placeholders ([*pagetitle*], [*content*]...);
4) replace menus (and other features) with snippets.
5) that's basically it.

For additional content options you can use Template Variables.

For the form processing, use the eForm snippet to handle this. It may have been installed as part of the bundle, otherwise it is available in the repository. There are good docs in the /assets/snippets/eform/docs folder.

To learn on-the-fly and build a site in MODx in 3 days is a bit over the top. It can definitely be done in less once you have the basics down. if you have the working site coded that is a great starting point. Use the working HTML as a base for your template and go from there.