We launched new forums in March 2019—join us there. In a hurry for help with your website? Get Help Now!
    • 7231
    • 4,205 Posts
    I still wish it was easier to figure out how to use custom Snippet calls: I always have this feeling that there are so many cool options with Snippets that are hidden from me. Maybe the new documentation will expand on this area?
    I know the feeling. However, the more you use the snippets the more things become clear.

    There are a few regular places to find documentation, this is where I look (in this order):

    1) inside the actual snippet, most snippets have at least basic documentation right in the snippet code;
    2) in the assets/snippets/snippetname/docs (or some variation);
    3) Forum and Wiki or mini-site (like with Ditto);

    The thing is that there is no real rule, some have it in one place while others will have different versions spread out through all the above. One example is Wayfinder that ships with docs for version 1.0, has great documentation in the MuddyDogPaws site but not 100% up-to-date, and has an unofficial full version 2 docs in the wiki as a download (which is greatly overlooked...I just noticed it the other day). Depending on where you look you will have a different understanding of the scope of Wayfinder...this is very confusing specially for newcomers.

    Therefore my tip is to never think you have read it all, it is always a good idea to check in a few more places before being sure that you have seen all the docs. grin
      [font=Verdana]Shane Sponagle | [wiki] Snippet Call Anatomy | MODx Developer Blog | [nettuts] Working With a Content Management Framework: MODx

      Something is happening here, but you don't know what it is.
      Do you, Mr. Jones? - [bob dylan]
      • 25883
      • 128 Posts
      Quote from: Photowebmax at Jan 03, 2008, 12:56 AM


      My idea was to write a A to Z diary of how to create a site with MODx. Start with a rough pencil sketch of the site and list the dynamic needs etc. Then a quick review of how to create the design in Photoshop, setting the dimensions and slicing up the graphics. Then comes creating a basic HTML template and getting the CSS down (using the graphics.) Then comes the MODx part: quick review of the install (easiest part) and then creating the foundation MODx Template. After that comes creating a menu dynamically and a review of the Manager and how to edit pages. Then the critical part: adding the various Snippets to make the site function. This is the area where most new users get lost, confused and frustrated (like me). Include a review of the most common and useful MODx Snippets that included details on what they do, how to install them and how to get them to behave. A list of the most useful Snippet calls for each Snippet would be great as well. I think a menu of Snippets for the most common type of dynamic sites would be useful. So, you could say "if you are building a community site with multiple web user bloggers you need the following snippets..." or "if you are building a brochure site with e-commerce you need the following snippets..." and so on. Showing graphics that indicate how the all the options and snippet calls works would be great as well. This would be a major task but if you had someone who knew MODx well and new how to communicate to users in ENGLISH then I think such a diary/tutorial would be most welcome. Not sure if that person is me but the idea is buzzing around that empty space between my ears.

      Videos are awesome as well. I was confused with all the geeky lingo on getting PHP and MySQL running on my Mac and then a I found an online video: the guy walked you through it SLOWLY and you could SEE every step he did. I watched it twice and after that it was easy...

      Quote from: Photowebmax at Dec 21, 2007, 08:18 PM

      The online documentation lists all the features of MODx and explains the Editor pretty well. What is lacking is a well written guide that would explain to new users how to approach MODx from the install onwards. What’s all that stuff in the MODx folder? Where does your HTML files go? Were do you put your CSS? How do you plan and implement the dynamic content? This is why a new Beginners Guide would make sense: these new user "crises" questions would not have to fielded as often...

      STEP BY STEP TUTORIAL

      A great TUTORIAL would cover most of these steps: creating a "project" for the most common type of dynamic website. The tutorial would build a full featured example site from scratch: well worded set that covers step by step instructions on installing MODx, setting up a site hierarchy, establishing Templates, Snippets, Chunks, adding HTML, adding CSS to build a starting HOME page. Written in straight forward ENGLISH. Often tutorials assume users know programming or the special terms involved. Then move on to step by step instructions for adding new pages while introducing Template Variables. Pictures illustrating the steps along the way would be great. Then introduce some added Snippets; for instance downloading, installing, and using MaxiGallery and eForm (all demonstrating actual samples). Then include procedures on backing up your work. Then show how to use the Editor and upload text, files and images. Maybe walk through all the steps involved in creating eCommerce and Forms etc, etc, etc. <Obviously a MODx tutorial is not the place to teach XHTML and CSS.>

      I see a TROUBLE SHOOTING Guide as a big plus. Maybe list common errors, error codes, Snippet call mistakes, caching problems, browser issues, operating system differences etc and what to do about them.

      I know this would be a big undertaking. But having this kind of "blank page to finished novel" guide would go a long way of gaining traction for MODx and eliminate much of the "how do I get this to work" frustration that new users go through when installing MODx. Overall I find some of the documentation is useful. But some of it is very inconsistant when viewed from a new user point of view. This is true of many computer system instructions: some instructions are very detailed and others zip through critical steps: like having detailed instructions on how to open your vehicle’s hood and prop it up but then saying "once the hood has been opened and secured you then change the engine..."

      Max,

      This was a good idea when you first wrote about it last December and still is now. Lots of well organized thought went into your post, this is a great framework or foundation for some of that work to begin.

      Sort of like, we’ve developed this great system, we’ve organically talked about it, expanded it, and developed all this information about it.... now lets ORGANIZE the information so that a new group of people who are ready can start to use it efficiently and effectively.

      (And, forego having to reinvent any wheels along the way.)

      The forums here are great, but as Max said, we have so many excellent and advanced developers that newbies if they’re not tenacious sure can get lost, kind of like sending a 3rd grader into a huge college or law school library.

      One thought: with the work that would be required to elucidate this, it could be a book. Maybe a free e-book download and a purchasable hard copy so the writers get something for their time? There are many co-writing/collaborating portals out there on the web, maybe some of us could get together and start something.

      The Wiki is great and certainly a great achievement, but, this would be an even higher level of organizing this information. And I think video would be an even more cool/new/different way of decanting the information and getting it out there.


      Quote from: Photowebmax at Dec 22, 2007, 05:16 AM

      Let me know if you need any help. I can read through your lists etc. It might be advantageous to have someone read it through the eyes of green newby (like myself...)

      I recently signed on as an independent contractor for a tech services firm: building brochure sites for their clients. One of the things I am working on is creating a FAQ & Questionnaire White Page that will help clients pinpoint and list their requirements/preferences for what they want from their websites. Helping folks identify these areas goes a long way to creating the building blocks required for getting the sites completed efficiently.

      Max


      Max, I understand if what you developed is proprietary, but if you’re willing or able to share, I’d certainly love to give that a read! And probably make some changes to make it my own and use with my clients. I agree with you completely that the intake process is a keystone to success.


      The last comment I have to make, and it won’t be a popular one, is that the Nucleus CMS I used to use seemed to be really easy for a beginner like me to grasp. Now I want to do more, and have more options, so I’m beginning my journey with MODx. But, I wouldn’t hesitate to recommend Nucleus to anyone who feels that MODx is a little over their head and too much to grasp at the moment. They have a great group of people on their forums as well. Someone might come across this post and that might be the perfect answer for them at this time.


      Excellent topic!

      John
      • John,

        Those are some great comments about Max’s OP. I think that if someone wants to write about MODx or write How tos that would be apprecitated.

        You will see over the next months and year that there will be many changes to the way information on the MODxcms site is presented. You will see improved documentation, more tutorials and less clutter. In addition there is a bit of an effort afoot to write a book with some of the team but others could be encouraged to do their own.

        I had thought about working on a book on MODx but I realize that I need to help out with others as well I need to put food on the table today so I leave it for a bit. I am hoping to do some screencasts for newbs if I have some time in the next weeks as I have some projects winding down and a couple more sane projects starting.

        If you have suggestions as to how information for newbs could be better presented please feel free to let the team know.

        Sincerely and all the best,

        Jay
          Author of zero books. Formerly of many strange things. Pairs well with meats. Conversations are magical experiences. He's dangerous around code but a markup magician. BlogTwitterLinkedInGitHub
          • 25883
          • 128 Posts
          Thanks, Jay,


          I’m warmed by your response and happy to see that the team acknowledges and is aware there’s a need there. That’s refreshing.


          I used to be a teacher, and I work with a website client who used to be a teacher. So, we talk about things like this, and, I would say an excellent guiding principle would be, when writing documentation, "How would I explain this to an eighth grader."


          The more amusing thing is, when I work with older clients, who have established businesses but are getting on the internet for the first time, when I explain concepts and needs and options to them, I have to take it even a step further, and I have to use the principle of "How would I explain this to a fourth grader who I really love." That implies all the wishes and hopes we have for the person and for their success and understanding. And when I do that, its appreciated, so very much.


          Glad to be in touch with you.


          John
            • 23299
            • 1,161 Posts
            Hi John,

            Its interesting that this old thread of mine got found again.

            I am very much with you on your thoughts and input on the documentation for MODx. I keep playing with it and then go back to what I know: static pages driven by CSS. And then I come back, only to realize that there are big gaps in my working knowledge of MODx, PHP and scripting languages etc.

            I think wishing for a "magic" documentation that will make setting up and customizing a complex site built on MODx might always be just out of reach somehow. I feel that this is not the fault of MODX or the developers involved, rather it has more to do with the power of the MODx framework itself...

            MODx is a foundation for building dynamic sites. Its power is in its adaptability: sure you can download the base install and start adding custom snippets like any other CMS out there. You can also build your own site with your own design and CSS system and pour it into the MODx framework. There are so many ways of doing things. Thats the power of MODx. But how best to illustrate that power and get users to show others why its a great tool?

            The best way of getting used to MODx is to spend time with it. Creating several local test sites at the same time really pays dividends in learning the system.

            What I still struggle with is the whole concept of bending the system and the snippets to make it work for specific site features. I will follow questions posted on this forum on "how to do this" and "why cant I do that", and I am amazed at the responses from folks like Susan or Doze etc: how do they come up with this stuff?  Folks like these seem to casually throw out code and custom snippet calls to make stuff work. To me this is where I wish there was a "how to guide". Installing MODx and getting it running is already covered. But how do you make the individual pieces of MODX sing like a Choir? How do select from the wide range of MODx features and custom snippets to create a great site feature set?

            What I would love to see is a tour of tutorial sample sites that demonstrate how it all comes together for a set of robust dynamic sites that really capture the cutting edge power of MODx.

            The geeks get it. Well good for them. But there are tons of creative designers who don’t have the geek tools or mindset. They want to create not code! I still see MODx as a CMS framework system that is waiting in the wings, ready to explode... If it can be demonstrated to the creative designers, pixel pushers and and those who find all of the other CMS offerings too limiting in their tight structure requirements. Maybe the new version of MODx and the documentation that will follow will become this watershed moment? But like you say John, it needs to be explained and demonstrated in such a way that it will capture the minds, imagination and hearts of the many "seekers" out there who are so ready to embrace the next best tool...

            Max
              • 18367
              • 834 Posts
              Max,

              like many others I share your thoughts. There are many posts throughout the forums pretty much covering the same theme "lack of decent documentation and requests for basic help"

              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.

                Content Creator and Copywriter
                • 3749
                • 24,544 Posts
                Quote from: Photowebmax at May 26, 2008, 01:32 AM

                The geeks get it. Well good for them. But there are tons of creative designers who don’t have the geek tools or mindset. They want to create not code! I still see MODx as a CMS framework system that is waiting in the wings, ready to explode... If it can be demonstrated to the creative designers, pixel pushers and and those who find all of the other CMS offerings too limiting in their tight structure requirements. Maybe the new version of MODx and the documentation that will follow will become this watershed moment? But like you say John, it needs to be explained and demonstrated in such a way that it will capture the minds, imagination and hearts of the many "seekers" out there who are so ready to embrace next best tool...

                After spending a fair amount of time pondering this recurring question, I sometimes wonder if it’s even possible. As you say, for those of us with a strong background in programming, it seems obvious how to toss off a custom snippet or make use of TV’s, @bindings, and the programmatic hooks built into MODx to get what we want. Unfortunately, even the most carefully written tutorial will only help users solve a limited set of problems and can’t give them that programming background or the necessary way of thinking about the problem.

                From reading this forum, I’ve come to see that many, many folks have needs that require custom programming to achieve. No generic tutorial or explanation is likely to help them very much. Certainly good beginner tutorials on Ditto, Wayfinder, Personalize, MaxiGallery, eForm, WebLogin, etc. will help get people going, but it’s pretty hard to reach that next level without not only a desire to become a programmer, but a real love of doing it.

                In a lot of cases, it might be a more satisfying solution to team up with someone who already has the skills. I, for example, love solving web site problems with programmatic solutions. I also enjoy designing the structure and navigation of a web site. When it comes to visual design, SEO, and .CSS, however, I barely scrape by and I don’t really enjoy the work. One of my web sites has great custom programming, but I’ve been meaning to spruce up the menu for over a year now (it still uses the default Wayfinder menu with no tpl at all). Several of my sites desparately need SEO work, but I keep putting it off. Teaming up with someone who loved visual design, SEO, and .CSS and excelled at them would make my web work that much more satisfying and, as a bonus, more productive.

                Bob
                  Did I help you? Buy me a beer
                  Get my Book: MODX:The Official Guide
                  MODX info for everyone: http://bobsguides.com/modx.html
                  My MODX Extras
                  Bob's Guides is now hosted at A2 MODX Hosting
                  • 23299
                  • 1,161 Posts
                  Great post Bob! As always...

                  I guess its like wanting the best Swiss Army Knife but avoiding the instructions that explain how to open all the tools etc...

                  I am a pixel pusher. I have been a professional photographer for years but also like design. I like hardware and cool software. I like Macs.

                  I also have evolved into a web designer as a result of the transition from wet darkroom to Photoshop. I like CSS...

                  But there always seems to be this divide between the "design" world and the developer "geek" world. Please don’t take my use of the word "geek" in a negative light. I am in awe of the skills and coding knowledge that these developers and code jockeys possess. In short I am envious and I use the term in a positive manner.

                  Design studios and web firms have the luxury of offering and using different people with different skills. Its rare to find a single person who has equal skills in both the design and developer coding worlds. But a lot of folks aspire to wanting to don all these "hats" at the same time. I am one of them.

                  But who can be a proficient pro at Photoshop, Illustrator, design, typography, color, layout, XHTML, CSS, CEO, Flash, PHP, MYSQL, Ajax, Javascript, browser issues, and CMS systems etc? Its really hard...

                  But quite often I am amazed at the skills of the developer as I am envious of the skills I do not have. What is also interesting is going to the sites that these smart people have and often finding them so lacking from a presentation and design standpoint. Which just gets back to your valid point Bob...

                  But the nitty gritty is that I for one feel that MODx could be the magic bullet that a lot of the design world has been waiting for: it has the power and flexibility to make the personal vision shine.

                  With this in mind I am eagerly waiting for the new versions of MODx and other developments that these smart developer folks will come up with...

                  Max
                    • 18367
                    • 834 Posts
                    I think it would be a great shame and huge missed opportunity if MODx became a programmers’ only domain. There are plenty of those type of solutions already, and they never make the next step up.

                    I think what attracts non programmers to MODx is its flexibility. We’ve tried other cms (in my case hundreds) and have eventually been frustrated with their inflexibility in certain areas.

                    We intuitively grasp that MODx holds the promise of something better. That it could be "the one" that makes all the difference.

                    As for the tutorials, many of the complaints are simply about getting started and getting things to work. We don’t need custom programming, we just need clearer instructions (as per my previous post.)

                    The other area where I think confusion arises is that many engineers and programmers (in general) have a tendency to overcomplicate things. (Please don’t take this personally, it’s just a general observation.)

                    In that, regard programmers probably aren’t the best people to be writing the tutes or the documentation. These should be written by people who understand human learning and communication.

                    EG: When people say they want more documentation, what they really mean is they want documentation that better explains what’s going on. It may not necessarily involve writing more words, just better words or graphics, diagrams and pics.

                    Many of my queries on this site have been answered in two short sentences.

                    There is another alternative that has been suggested by others, and that is to simply turn on something like Camstasia or screen cam and record how you do things and what you do. Then post it as a common av file, podcast even.

                    Just seeing how something is done can make all the difference.

                    Once we all make it to base camp, then we can talk about custom programming, if it’s even necessary.

                    For many of us a basic install of MODx with everything working is probably CMS heaven.



                      Content Creator and Copywriter
                      • 34017
                      • 898 Posts
                      It took me about 6 months, on and off again, to figure out MODx. And doing anything new in MODx almost always takes a learning curve- Jot, Wayfinder, Ditto, etc.

                      Documentation is so difficult because setting up (Ditto or Wayfiner or Jot) is a multi-step solution- where one mis-typed ` can make it not work. Then many of us know to check the cache, check for missing backticks, etc. I also think part of the ’problem’ is the devs have really pushed the 096 core to its limits and suffer from old etomite terminology.

                      I think it does take a while to get the ’gist of it’. But once you do, you’ll save so much time in the long run. But it really does take time to become unshackled from the normal CMS procedure and boxiness. I tell everyone to do a few things to begin MODx:
                      - install 2 sites (one with the default content and one blank)
                      - add your template for the base site. Put MODx calls in it.
                      - add a second page
                      - replace your current menu with Wayfinder. Make Wayfinder work the way you want with your current template. Do a View-Source to see if it works right.
                      - replace the content of your site with [*content*]
                      - repeat the Wayfinder steps to learn eForm or Ditto (I think eForm would be easier)
                      - add one text TV and place it one of your pages.
                      - once you figure that out, try a TV with delimited list output (the widget stuff drove me crazy at first. I think a better explanation of this would help a lot of people.)

                      The above all takes time. You may need to let it rest a little bit and come back in a week. The key to me is:
                      - with Joomla, the module or component creates ALL html output
                      - MODx creates puzzle pieces (placeholders) that you can control every aspect of the html output (ie links, classes in Wayfinder or report form in eForm)

                      The wiki has made things 100 times better from when I first started this process. But documentation is the toughest thing for growing software. I think it takes (1) working through your site, (2) going step-by-step with the wiki tutorials, and (3) time to understand how chunks, snippets, tvs, and placeholders work.

                      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?

                        Chuck the Trukk
                        ProWebscape.com :: Nashville-WebDesign.com
                        - - - - - - - -
                        What are TV's? Here's some info below.
                        http://modxcms.com/forums/index.php/topic,21081.msg159009.html#msg1590091
                        http://modxcms.com/forums/index.php/topic,14957.msg97008.html#msg97008