Some General Principles

[calguy1000]

Okay, some of these topics have been touched upon in past posts, but nothing definative has been written, so
I thought I'd write a few notes about CMS made simple, how it's made, and the underlying reliance on smarty.

I intend here to make this topic sticky, and it should be one of the first things you read when you're asking 'How Do I....'. Most of the time, the information you need is at hand, all you need is the knowledge in how to extract it.

I intend to treat this thread as a work in progress, and will periodically update the top post, in the intents that this will someday work its way into the official CMS documentation, so stay posted people.

1) CMS Made Simple is largely built around smarty (smarty.php.net).
    This is the power and the beauty behind CMS made simple.  It allows for infinite expandability and customization
    without modifying any php files (most of the time).

    Therefore, whenever you see a template (page template or module template) smarty is being used, and
    you can probably use all of the smarty capabilities inside of them.

    The {content}, {news}, {menu}, {stylesheet} and other tags are just smarty plugins that have been written
    by Ted, and others, to enable reading data from the database and providing that data to smarty in one way
    or another.

    Anything with {$xxxxxx} is a smarty variable that can be tested, converted, adjusted, and displayed from
    within your templates. 

    Similarly {cms_module} is yet another smarty plugin that interacts with the database, and with the module
    code itself to pull out html code.  Most of the modules provide templates that allow you to adjust the output.

    All users of CMS made simple need to read the documentation at smarty.php.net/manual to understand alot
    of what they can do.  If they're still lost, then they should take a look at the News default templates, and the
    menumanager default templates, and there you should see that all of the magic in them is just smarty manipulating
    the data that was provided by user written php code.

    Inside of any CMS page, or  module template you can use smarty logic, expressions, modifiers, or other plugins
    (including many CMS plugins).  The functionality is limitless if you have a bit of an imagination, and the willingness
    to learn. 

2) When editing page, or module templates, sometimes it isn't obvious what variables are available and how you
    can use them.
    For this, you need two things:
    a) The {get_template_vars} smarty plugin
        This smarty plugin is used in debugging and development to list all of the variables that smarty knows about
        and their types.  When working in any new (to you) template you should use this to see what variables are
        available.

      The get_template_vars plugin will pollute your output, but that's okay, it's just for debugging and development.
      When everything works, you can remove it from the appropriate template.  And... if you're really worried about it,
      you can put that inside of an HTML comment, and then just look at the output when you do a 'view source'. 
      i.e.: 

  b) the "print_r" modifier
      building on step a above, sometimes the {get_template_vars} plugin will tell you that something is an 'Object'
      or an 'Array'.  But it won't tell you what's inside of it.  There is a built in smarty capability to use (some) php
      functions to expand the contents of these 'hidden' items.  One of the functions you can use is print_r
      i.e:  {$myObjectVariable|print_r}
      This will generate a list (recursively) of all of the contents of that variable. 

3) Smarty is Reentrant/Recursive (whichever).
    (To truly understand recursion, one must first understand recursion)

    Anyways, in a nutshell, it means that smarty variables can be declared pretty much anywhere, and be available in
    your template.  For example, if you had the following code inside of the content of one of your pages:
      {assign foo='bar'}
    and, your page template was similar to this:
      {$content}FOO = {$foo}
    You would see the output:
        FOO = bar

    You may think that that is a trivial piece of information.  It isn't.  It means that you put calls to one smarty plugin
    within the template of another.  They can be nested as deep as you need (it's just a matter of memory and time
    limits).  i.e:  This technique is used to allow comments to be used on News articles, or to allow you to embed
    smarty code within your News content....  think about it a little.

4) Smarty is linear
    That means, that variables and tags that are exported lower in your template my not be necessarily available above. 
    It also means that you can export information from a lower level template into a higher level template
    (as long as the higher level template is called 'after' the lower level one).  As well, variable from one module
    call can overwrite variables from another.
    For example, if you were to use this as a page template:
      {get_template_vars}
      {menu}
      {content}
      {get_tempalte_vars}     
    You could, and probably would see different variables available at each step.

[Added: April 16, 2008]
5) Website developers and designers should not be using wysiwygs, at all... period. They're for content editors, and content editors only. 
    - If website developers and designers can't make a website without using a wysiwyg, they should probably go back to school.  If they can't go back to school, then learn to use GOOGLE.
    - I recommend separate login accounts for content editors and designers/developers... and only the content editors should use wysiwygs (because they're expected to know how to write in whatever spoken/written language your content is to be displayed in, not how to code HTML).
    - Website designers/developers may not have the best grasp on the punctuation and grammar of the destination language, but should know HTML and CSS without having to use a wysiwyg.

6) Don't mix page logic, or module tags in pages that customers will be editing.  This allows the website designer and developer to turn off the wysiwyg.
    - Users will screw something up if there is the slightest possibility, so don't give it to them.  If your customer will be editing a page that has smarty tags in them, move the smarty tags into the page template.

7) Wysiwyg editors should be trimmed down to such a point that the end user will have a tough time messing up the appearance of your page
  - This means removing buttons, limiting styles, and tags that are available to your user to such a point that it's reasonably hard for them to mess up the look and feel of the page.

[Pierre M.]

Hello,

(Smarty)allows for infinite expandability and customization without modifying any php files (most of the time).

Yes, i'd like to stress that : CMSms users can build websites without PHP coding. It is better if they understand well HTML/CSS templating. But they can use even prebuild themes (and modules, of course).

    All users of CMS made simple need to read the documentation at smarty.php.net/manual to understand alot
    of what they can do.

I beg to differ/precise : I think you are talking about power users. I think "just user" has no need to know about Smarty being under the hood.

I'm ok with CMSms being built on top of the Smarty templating engine (yes, it makes it simple and powerfull). I agree that "The functionality is limitless if you have a bit of an imagination, and the willingness to learn." And this nice how to is very good for people making advanced templates and coding modules (thank you very much for sharing it : I'm learning things).

I just want to make it clear for newcomers that CMSms is still simple for people without coding knowledge. Do you think it would help to rename the topic "Some General Principals for advanced users" or something like this ?

Pierre M.

[Nullig]

Excellent info.

I agree with Pierre - I think it should be stressed in the title of this sticky that this is info for advanced users, lest you scare away the "non-coders" who are looking at using CMSMS.


Nullig

[calguy1000]

I disagree.... CMS Made Simple is not designed for my father or grandfather, or even my girlfriend to build websites with (as I get slapped).  If it was designed for them it'd be alot simpler (think frontpage, but that's already done).  It's primary target is people who develop websites for a full time, or part time living.  People who know about (at least most of) the concepts like XHTML, CSS, Cascading CSS, separation of design from content, re-use of design. Know about databases, and the advantages and disadvantages thereof, know some things about pretty urls, SEO, re-use of code, and what it takes to develop a professional semi-static website.  These are the people we're marketing towards: The people that know the output they want, they just want to be able to do it quickly and easily.  Not my brother, not my mother, father, grandmother, aunt or girlfriend.

What we should not do however, is explicitly exclude people that are new to HTML, CSS, XHTML, PHP, databases, websites, remote servers, hosting environments, etc. though we do should not IMHO make efforts to  support them.  Infact, IMHO, if they want to use the system, that's fine.  However, I think we should not support those people until such time as they've gone through the paces.... spent the hours searching through google for answers to questions, learnt concepts such as 'what a database is', 'what a file permission is', what the 'Cascading' means in CSS. how to troubleshoot problems on their own (httpd error logs anybody?)  and most importantly, know how to type things into a search field in the forum to get hints to answers, documenation, or hints as to where to research further.

My reasons behind this are as follows.  1) You can't please everybody all of the time.  You can't even please everybody a large percentage of the time.  2) If we're designing this product for people that are new to the world of web development and just want to put their website up so that their grandparents could see some new baby pictures,  then the product would be alot different (see frontpage).  3) (relates to 1 above).  We can't design a product for web developers to be able to to do their jobs proficiently and quickly, whilst keeping the noobs in the dumb about everything.

[added] 4) We have limited support resources. we can't possibly support everybody's little problem with layout, design, colours, permissions (mostly), database access problems (mostly), memory limits, and alot of other issues.  We need to focus our efforts on the core audience, the people that know what they're trying to do, but are having problems (possibly due to our package), getting it done.  IMHO we shouldn't be providing support for mod_rewrite, mod_security, mod_*, IIS specific issues, or anything else once we determine that its not a problem with our package.  (However, I have no problems with the community supporting itself, it's just that users should not expect support (as it happens often enough) from the team.

Users new to (X)HTML/CSS/Content Management systems don't care about that.  They want to get something up on the internet that looks cool, has their pictures on it, maybe a sound file or a video or two, and didn't cost them much time.  Usually they're used to packages like word.

Web developers want functionality a certain way.  They want to be able to develop a website quickly with the functionality they need.  and to easily utilize addons,  They also want a tool that won't get in the way of them developing a SEO optimized, CSS and HTML validated, Templated system, where others can then assume the responsibility of adjusting content, etc.  Web developers are accustomed to research, and think 'google' when they don't know something, Web developers know that people adding/adjusting content on their sites don't know HTML/CSS/databases/file permissions, etc.  and are used to word,  so they have to provide some type of WYSIWYG editor so that the editor/adjuster of content will be somewhat comfortable.  But then they have to think..... how can I limit the WYSIWYG editor so that the editor/adjustor can't screw up the deisgn.  And they cringe even thinking about it.

We were all noobs at one point in time.  Infact, my CSS knowledge is intermediate at best (though sometimes I think it's better than that).  As well, I've asked some really stupid questions myself at times.  Sometimes I've gotten answers, sometimes I haven't.  But I didn't expect the product that I was using at the time to bend to me.  I expected that I would have to buck up to the task, and learn what I needed to learn.  And at least do enough research to be able to ask intelligent questions. 

Does microsoft answer questions for 'word' like:  'How do I change the colour of this text?'.  Does frontpage come with handholding support for grandmothers?  The answer is: only if you pay them the support fee. 

In a nutshell, this is what I'm asking of our users.  They should know what they want, do significant research first.  show that they have done it, and then, if still having problems, then ask an intelligently worded, well researched question.  Our users shouldn't expect free answers out of us that they would have to pay for elsewhere.  It doesn't matter who they are or what their site is for, how big of an emergency it is to them, if it is my grandmother, or if it is a web development professional.

People that do web development as a profession, or even on a part time, volunteer basis should be accustomed to the research, constant learning, and to understanding, at least to a relative amount that 'I have to learn how to use the package'.

Just my $0.02

[Pierre M.]

Thank you for this clarification and expression of the "primary target".
I have stressed "no PHP coding knowledge required" because as CMS Made Simple very well deserves its name it attracts beginners (from what I see in the forums). I very much agree with you that people should "do significant research first" and "then ask an intelligently worded, well researched question".

Do you think it would be usefull to add a summary of this at the top of the requirements list ? I mean something like : "you should at least know about remote servers, hosting environements, PHP&SQL, templating, URLs..."

Pierre M.

[calguy1000]

Well we need something somewhere that describes 'who CMS is for'. 

And after looking at the requirements page, it needs more information about 'some modules may not work with the stock install, or with some databases, may require more memory, extra permissions, etc.

[halm]

Calguy - thank you for the coherent and accessible entry on Smarty. It clears up many issues and questions I've had about the tags used in CMSms.

About your discussion on target users: As you know from my postings on this forum, I set out with next to no knowledge about php, css or working with templates. At this point I am still a beginner, but I know more now than before and I'm learning as I go along. That's essential, as you both state above: That newbs like me understand that this is a learning experience, not a prepackaged solution. I knew coming in that I would have to make modifications to templates, stylesheets, and more. It's hardly even been a steep learning curve.

However, I for one would like to see a 101 page for total beginners, perhaps as an expansion of the requirements page? Alternatively, a caveat of sorts on the main page that installing and using CMSms is "like taking a holiday" provided have previous coding experience and/or know how to check applicable references (ie, CMS-wiki, handbook, IRC, whatever) But supplying a few general links on "need-to-know" subjects could be helpful.

This would serve a triple purpose; 1) Actually informing Word level newbies that this isn't going to be like WordPress' 5-minute install.
2) by applying the above, you might be able to keep Calguy's grandfather out
3) informing the people who decide on CMSms anyway how and where they may find solutions to the problems that will arise - without peskering people on the forum like I have...

Just telling that there will be work, because this is a tool for trained professionals (or professionals-in-training). In this context only does the "simple" part of the name make sense: It's no Rube Goldberg machine, more like a powerdrill. But you can make a real mess with one of those if you don't know how to use it. And you can use it without knowing all of its higher-level functions.

CMSms can be used by beginners and, being one myself, I would like to see just a teeny opening towards that group, but of course on the premise that the software is intended for more experienced users.

I admire the patience that developers and Support Gurus on this board show in dealing with newcomers, something sorely lacking in other parts of the open source community. Some "support" forums will hardly bother to tell you to RTFM!; if you're lucky they'll just ignore you.
You're a kindly lot, CMSms dev & support teams. Don't change!

[rab]

I've spent well over 2 weeks of serious effort trying to build a site with CMSms, and now realize that, for the non-programmer or newbie, it's most certainly not all that simple. In fact, I would say that a decent working knowledge of CSS, PHP and Smarty is a minimum requirement to build anything more advanced than a very basic and only nomunally interactive website. So, I can understand Calguy's position that CMSms is not intended for newbies, and that the support team shouldn't waste their time helping them.

But, and this seems to me to be a pretty big BUT, that concept doesn't jive with the CMSms sales pitch - the message on the homepage which probably entices a lot of newbies to try CMSms in the first place. Read it for yourselves:

"CMS Made Simple provides a fast and easy way to create a web site and manage its contents. Use it to make a home page for your family -- or your multinational corporation!!!
To get a site up with CMS Made Simple is just that, simple. For those with more advanced ambitions there are plenty of addons to download. And there is an excellent community always at your service. No question is too stupid to be asked!
It's very easy to add content and addons wherever you want them to appear on the site. Design your website in whatever way or style you want and just load it into CMSMS to get it in the air. Easy as that!
So easy, it feels like taking a holiday..."

That's not the type of language you use to sell to programmers - heck, it's really what you would want to say to sell to a newbie! And quite frankly, CMSms would be foolish not to try to sell itself to as many newbies as possible - growth, sustainable growth, is strictly determined by the numbers in this case. So I have a suggestion - devote some time to write a User's Handbook directed at newbies, with step-by-step directions, examples, screenshots, etc. Once you can get them started and headed in the right direction, I submit you'll be developing a strong base of CMSms supporters who can help other newbies while the support team concentrates on the real "webmasters".

For an idea of what this "How To" would look like, check out Zen Cart's new Beginner's Manual, or the "Drupal Cookbook" (written by a newbie) - both are real simple to understand, and explain step-by-step exactly how to build a site. In essence, more than enough info to get started and actually produce something without getting stuck in coding syntax, logic, compatibility, etc.

Because I've decided I need to learn Smarty if I want any chance at all to properly build the types of websites I need, I've also decided to check out the other 2 Packt winners (Drupal and Joomla) to see how simple (or not) their systems are. If I come back to CMSms, it will be with a promise to write that Beginner's Manual. And if I don't come back, maybe you'll think again about changing that sales message.

[starbits]

Thanks Calguy!  I appreciate your General Principles as I am your target audience. 

I would suggest adding another section to the documentation.  You already have "I am an editor, designer, administrator".  This is for the "I am a programmer" section.  Some of the discussion above relates to the point that a CMSMS administrator may not be a programmer and may be using the system "off the shelf".

I like the way CMSMS works because it seems fairly intuitive to me as a programmer.  I specifically don't know things like:
.  Smarty (I am reading the docs but it will take a while),
.  What variables are available to me when I write my own tags,
.  If I wanted to add a table of my own to the database are there shortcuts other than pure PHP code,
.  How I go about creating special password protected content for "members only".

The above are some of the things which I will need to learn for my second CMSMS site.  (The first one was easy.) 
So if you feel inspired to write more documentation, be sure I will read it!
Steve

[calguy1000]

I agree with Rab here, that the sales pitch doesn't exactly jive..... but I also don't think there is much wrong with it.
'Simple' is relative.  It means something different to you than it does to me, and means something different to everybody else.  To me, because I already had an understanding of how applications work, and a rudimentary understanding of HTML, CMS  IS Simple.  It's simple to install, simple to maintain, and simple to build 'simple' websites with because of it's logical separation of layout from content and a good set of pluggable addons. 

If you read here: http://forum.cmsmadesimple.org/index.php/topic,15734.msg78168.html#msg78168 There is knowledge you need to have to build a website (HTML and CSS).  There is knowledge that you need to have when working with a host (FTP, unix permissions, etc).  And there is even more knowledge needed when you use a content management application.  There is no getting around that.  People need to learn this stuff, it is not specific to one content management system, these issues occur with most of them from one time to another.  And as authors of a web content manegement system it is not our job to teach people all of this.  To wander down that road would result on us spending too much time teaching, repeating the same messages, and hand-holding new users through the same old tasks (we do enough of it already), rather than working on the project itself. 

Also, CMS Is not designed to be the 'be all and end all' of content management systems.  It works great when developing smallish semi-static websites.  It is not designed to be a blog, a community portal, or a replacement for myspace, for yahoo or any of those other specialized packages or websites.  It can do some of those functionalities, but it does not focus on doing them.  CMS excels at being a good 'middle of the road' web application, it solves many peoples needs in many different types of websites, by plugging in the standard and available addon modules in various combinations and permutations, but it cannot be everything to everybody.

CMS Made simple does not 'require' you to learn PHP.  Infact you can build quite a few websites with varying levels of dynamic functionality, private content, albums, videos, file sharing, etc etc, without ever seeing a line of php code.  If however the built in or third party addons don't do exactly what you want then you may need to get your feet wet with actual coding. or convince, or pay somebody to do the work for you.

[calguy1000]

Thanks Calguy!  I appreciate your General Principles as I am your target audience. 

I would suggest adding another section to the documentation.  You already have "I am an editor, designer, administrator".  This is for the "I am a programmer" section.  Some of the discussion above relates to the point that a CMSMS administrator may not be a programmer and may be using the system "off the shelf".

Yes, we need more programmer, and advanced docs, but many of these questions have been asked and answered numerous times in the forum.

I like the way CMSMS works because it seems fairly intuitive to me as a programmer.  I specifically don't know things like:
.  Smarty (I am reading the docs but it will take a while),
.  What variables are available to me when I write my own tags,

Use {get_template_vars} to see the list of available variables in a template, and if the entry is an array or an object, you can use {$variablename|print_r} to view its contents.  I've personally answered this question dozens of times.....

.  If I wanted to add a table of my own to the database are there shortcuts other than pure PHP code,

There's the formbuilder and formbrowser modules, but nothing that will create a 'table' that is layed out exactly the way you want without diving into code.

.  How I go about creating special password protected content for "members only".

This question has been answered numerous times, and there's even a visual tutorial in the wiki.

[lollipop27]

I found CMSms about 2 Months ago and started working with it. I already had a basic PHP understanding and a solid XHTL and CSS knowledge. So I think I have sort of the requirements. BUT, I'm not a programmer.

I just want to add two things why CMSms is convincing for people like me:

• this is by far the best, fastest and most tolerant forum I've ever seen. (No useless arguments about whether this is a stupid question or not ... etc.), thanks to everyone.
• CMSms is perfectly simple in its structure and way of deviding Layout and Programming, i.e. this means I can work on the stylesheets and (x)html files as I'm used to it, without having to know much about php

(I agree this CMS is not replacing Frontpage and one should first ask google before bothering the forum.)

So I think perhaps, you should add to your definition of the requirements these designers, that appreciate the "ready made" programming like me.

[dlpirl]

One important underlying assumption I've learned exists with cms ms is that it assumes web designers use css for page layout -- and of course cms ms program development is based on this underlying assumption. I can program, and and my wife is a self taught graphic designer, but only uses wysiwyg layout. I have tweaked css but not done css layout before. In researching how, I found this very useful link: http://www.htmldog.com/guides/cssadvanced/layout/ . Hope that helps orient some others and save frustrations.

[pixelita]

Hello,

    All users of CMS made simple need to read the documentation at smarty.php.net/manual to understand alot
    of what they can do.

I beg to differ/precise : I think you are talking about power users. I think "just user" has no need to know about Smarty being under the hood.

I'd like to expand that further, Pierre, if I may, and say that anyone who designs or develops web sites for other people using CMS-MS must understand the smarty templating system.  It's come in handy a few times, especially when figuring out smarty date formatting .. rather than bother the Forum with the question, I just found the information there.

So it's a must-read for a designer or developer -- or power user. 

I just recently found CMS-MS and am quite taken with it.  I am a Drupal/Joomla refugee. With its FEU modules, CMS-MS has it going on with being able to deliver different content to logged in versus non-logged in users.  Its form builder is elegant and intuitive and I had a complex form up and running, and thoroughly functional, in no time at all.  The Smarty tags took some getting used to, but they are also very powerful and that link that Calguy posted is a frequent stop on my web design/development forays now that I am concentrating on building CMSMS-driven web sites. 

[calguy1000]

Yes, smarty is the tool that allows bridging the gap between the programmer and the 'web designer' or 'web developer' that doesn't know php.  With smarty, and the thorough use of it that CMS entails, web designers and web developers only need learn a little bit of 'php like' syntax in order to pull off some very complex functionality, or flexible designs.

The web developer/designer I work with took to smarty in a matter of a few hours  and is now asking 'how do I do this in smarty' or 'is there a modifier or a plugin that'll do this' or 'how do I customize this template so that it behaves slightly differently for these 3 pages' etc, etc.  He understood the power of smarty inside of a couple of hours, and now uses the smarty manaul, the and stuff alot.

There's a drawback to that though..... he's now so proficient at smarty that I have to do a bit more programming to export enough variables from PHP to smarty to give him even more power to do even more funky stuff.  But those are the type of changes I don't mind.

I would have done FEU and SelfReg, Banners, Hitcounter, and other modules quite abit differently if even I had understood the power and flexibility back then.

So..... as CMS is not designed for 'website noobs' for a number of reasons I've already gone in to.... it's designed for web designers, web developers, and power users..... I would say that the smarty manual is 'required reading'