Fog Creek Software
Discussion Board




Knowledge Base
Documentation
Terry's Tips
Darren's Tips

How do you use variables?

I'm working on designing some improvements to the "Variables" UI and would like to hear how people are using variables.

We could greatly improve the editing experience for variables by having the variables window pop up the HTML editor (the same as you get for templates) instead of the current weak dialog box.

If we did that, though, and you typed, for example, "foo" into a variable box, you would actually get something like

<html><head>...</head>
  <body><p>foo</p></body>
</html>

as your variable. Of course we could pull out just the body, then you get
<p>foo</p>

which is still annoying if you want a simple variable to just be something like a copyright date which shouldn't be a part of a paragraph.

So the final idea is that if the entire HTML consists of one paragraph, we remove the <p>....</p> tags. Incidentally, CityDesk already does this for all the fields in articles... it leaves out the <p>...</p> if you provide precisely one paragraph.

On the other hand ... if you use variables to provide your end users with an easy way to type in commonly changing things (like, I don't know, the exchange rate? weather?) then you may not want to confuse your users with a complicated user interface like the Template editing UI just for innocent little variables.

Feedback is welcome.

Joel Spolsky
Wednesday, March 19, 2003

I guess you are talking about making the variable editor have normal and html modes?

I would hope there is a way to enter text without any html being added.

for instance,  css colors -- If i type #cc00ff I don't want it to be surrounded by any html

joel Goldstick
Wednesday, March 19, 2003

Yeah, like templates, it would have normal and html modes.

But then of course it becomes more confusing to end-users.

Joel Spolsky
Wednesday, March 19, 2003

thinking out loud, here...

You can always use an "article" when you want a rich, HTML variable... the old trick is
{$ foreach x in (filename "foo") $}{$ x.body $}{$ next $}

So maybe we should reserve variables for simpler, shorter non-HTML tidbits.

We could even add a bit of CityScript like

{$ include "filename" $}

which has the same effect as the foreach statement above....

Joel Spolsky
Wednesday, March 19, 2003

The variable dialogue needs a way to sort variables as I'd like to see them in alphabetical order and it would be good if it were resizable. Resizing of any dialogue should be persistent. It would also be cool if you could show where a particular variable was used. Oh and I'd like you to solve world hunger and poverty too. Thanks for listening! ;-)

John Topley
Wednesday, March 19, 2003

I'd say no extra HTML.  The template designer could add some before/after tags via other variables.

One of my users planed to use a variable for something.  I convinced him to use an article instead and did a "foreach 1x" to pull it into the site.  That was a lot easier for both of us.  There was a lot of risk for him to editing variables.  That's not the answer for everything though.

You didn't ask this question, but what bothers me is that once I open the window that lists the variables, I'm blocked from the rest of CityDesk: Can't edit articles or templates, can't edit two variables at once, etc.  With my short attention span, I need lots of on-screen reminders of what I'm doing.

tk
Wednesday, March 19, 2003

If the variable editor had Normal and HTML views, just like the article editor, and remembered which view the variable was last edited with, I think it would work OK.

If the person who sets up the site leaves text-only variables in HTML view, then next time a non-technical user opens them up for editing, they'll only see the text-only version. When they edit and save it, they shouldn't break anything.

I don't know if it's do-able or not, but it would be really cool if variables could be arranged under a folder-type tree. You'd still just reference the variables by their names, but the folders provide a way to group related variables together. For example, I could have all my colour-related variables under the folder 'colour'. This way, I could group together the variables I expect non-technical users to edit under one folder, and tell them not to touch anything in the other folders.

Darren Collins
Wednesday, March 19, 2003

Oh yeah, TK mentioned my biggest frustration with variables. Please allow us to edit more than one at a time, and to edit other stuff in CityDesk at the same time!

I hate it when I'm trying to pull common bits of code or text out of templates and articles, and have to keep opening and closing the variable window. It's painful.

Darren Collins
Wednesday, March 19, 2003

That workaround for variables Joel mentioned makes me think that there (duh!) multiple uses for variables.

I think Variables should:

A. Have properties such as "contains HTML, is a date, etc." This way you can have your copyright date in multiple formats.

B. Be audience/language/etc dependant the same way articles are. For example, I'm developing for PHP, but need different database connect strings for different environments. The current workaround is to do this via articles with audiences, but this is really the work of variables.

C. Can be turned on and off in the non-developer's view. This way they can't edit the database connect string, but can change the copyright date.

D. There should be global variables for things like total # of articles/files, total site size, last upload date/time, etc.

That's all I can think of right now...

www.marktaw.com
Wednesday, March 19, 2003

Here are some semi-related ideas while I'm thinking of them.

What about split-screen development Similar to the newer Dreamweavers? This way we can see the code & the preview at the same time. This way we'd always know if we were adding HTML to something accidentally.

Then a way to lock it into one or the other view for the end user - variables = always text, articles = always html, files = user can select

www.marktaw.com
Wednesday, March 19, 2003

These are all good ideas, and we'll probably implement a lot of them...

but...

please do take a moment and tell me how you actually use variables now:

* do you provide variables for your end users? or just use them to make programming a site easier?
* do you have long variables? short variables? HTML variables?

The more I know about how variables are actually used, the better I can optimize things like the default size for the variable form, whether Enter should dismiss the dialog (good for short variables) or not (good for huge variables with lots of HTML), and so on.

Joel Spolsky
Wednesday, March 19, 2003

Right... I just took a look and I don't use any variables today.

I think the way I use variables is intimately tied into the way I use templates, which is intimately tied into the way I use CityScript.

www.marktaw.com
Wednesday, March 19, 2003

I usually use HTML variables, leaving the articles or .htmls as simple as I can.

I usually combine variables with citydesk scripting, for tittles, etc.

I see my "variables" are most static (constant along time) and usually I dont change them. I ask me if I'm using them correctly.

Roberto
Wednesday, March 19, 2003

Hi!

I use variables for a lots of things.  Color codes, so I don't have to change every template.  HTML snips, such as the header and footer of my site.  I have different templates, but the top and bottom are all the same.  This is stored in a variable.  Keyword list is stored in a variable, and so is the title to the website.

I am the only one who uses the variables (no usage by user).  If I need to edit the html, I just copy from the variable, paste into my html editor (GoLIve), make the changes, and paste it all back into the variable definition. 

Not sure exactly what you meant by html in variables, but if you are talking about adding extra stuff to variable, like formatting, to what we enter, I would not like it.  The variable should be used as entered.  Otherwise, we would have a variable variable ;)  Not sure I can take that.

My 2 cents worth....

JEff Kolker
Wednesday, March 19, 2003

I'd love it if instead of colors available in the regular UI, they were developer definable so that a highlight color that works against a black background for one version of the site would still work against a white background for another version of the site - i.e. we could say "using template family x it's #eeeeee, and using template y it's #333333"

This is somewhat tied in to variables.

www.marktaw.com
Wednesday, March 19, 2003

I use variables in many ways (as I am the programmer and the end user). I have variables :
- with scripts (such as several types of 'related' article lists for sidebars)
- with some html
- many without html

I do agree with Darren in that there are many types of variables and it would be great to treat them as such.

A problem I have with the current variables (besides the limited user friendlyness) is the inability to place partial scripts in them. (e.g. just a (and(or)) condition) to be used within foreach loops.

Adriaan van den Brand
Thursday, March 20, 2003

I use Citydesk to prototype web applications, and most of my prototypes have 50-150 variables. Most of the variables are HTML snippets, so I can do things like this inside the articles:

{$.table_start$}

{$.row_start$}
{$.row_td_start$}Name:{$.row_td_end$}
{$.row_td_spacer$}
{$.row_td_start$}<input type="text">{$.row_td_end$}
{$.row_end$}

{$.table_end$}

I'm the only person who edits them. Things that would be useful to me:

- Joel's 'include' idea, although I would rather see it based on magic name instead of filename

- The ability to pass in a value to a variable (i.e., {$row_td "Name:"$}

- handle larger variables better (bigger window, resizable window, "enter" makes a new line instead of closing the window, etc.)

- The ability to import/export variables

- The ability to do other things while editing variables

Having the ability to swith to the HTML editor while editing the variables would just be an annoyance to me. I want to control exactly what's in the variable.

Jim Corban
Thursday, March 20, 2003

I have the following in variables :

- colour settings for the stylesheet
- the whole of the <head> ... </head>, because it's the same in all my templates
- a bunch of sidebar elements (including menus and a form for Atomz search) which my templates use in various combinations
- obfuscated email addresses
- a 3-variable trick which makes a bible passage lookup form to open the passage in a new window (used like {$.b1$}description of verse{$.b2$}verse reference{$.b3$})

My gripes would be :

- having to remember ctrl-CR at the end of a line
- the modal dialog

I don't miss HTML editing at all, what I'd most like would be a non-modal proper text-editor - or even the ability to edit the variable text in an external one, ie "open with".

Michael Wild
Thursday, March 20, 2003

I recently used a number of variables containing ASP include file comments.  I setup a site so that CityDesk is publishing pages with .asp extensions.  As an example, I have a {$.LoginForm$} variable.  On the actual login page, the user has this variable and they can put any text they want above or below or around the login form.  It frees me up to do just what needs to be coded and allows them to enter the content they want to add.

Wade Winningham
Thursday, March 20, 2003

I like long variable names, such as CSSStyleSheets, NumberOfArticles, and longer: I use a LOT of variables, so I like to be as descriptive as possible.  I, too, would like a way to resize the variable dialog, sort the variables, and not have to dismiss the dialog to bring up another window.

I don't care what the environment is as long as it is larger, doesn't close itself when I hit enter to go to the next line in the editor (oh yeah I have to use CTRL-Enter here), and that if it inserts HTML codes I have the ability to remove them and that it will respect that and not try to reenter them or garble what I entered.

Here's how I am now using variables:
- I use the standard SiteName and TagLine.
- I use an author name variable to link author names to an author bio pages (I put it in the about field so that I can still do compares against the author field.  I have one variable for each author, like this PhyllisEileenBanks -> <a href="PTMFOG0000003600">Phyllis Eileen Banks</a>
- I use variables for special characters such as "smart quotes", EM and EN dashes, and bullets. These look like this: &nbsp;&#8211;&nbsp;
- I use variables to contain the entire HTML code for the top and bottom of article pages.  Note that the template has the HTML, HEAD, and BODY tags.  The top and bottom variables contain tables of logos, breadcrumb and other navigation stuff.
- I use variables to keep frequently used Chamber of Commerce information then put the variable in the sidebar of any article in the geographic area of that Chamber.
- I use variables for copyright dates, phone numbers and addresses.
- I use separate variables for the Month, Date and Year for updating a newsletter plaintext template.  More HTML here would be a real pain that required postprocessing to strip out the tags.
- I use it for colors, though the DHTML editor garbles them if I ever switch the template from HTML to normal mode :(.
- I use variable for the bottom navigation bar.
- I use a variable to pull in CSS stylesheets:
<link rel="stylesheet" type=="text/css" href=="PTMFOG0000005072.css">
<style type="text/css">
@import url(PTMFOG0000005073.css);
</style> 
- I use a variable to calculate and print out the number of articles on my site:
<script language="javascript">
var tmp = "{$ foreach x in (and (not (or(keyword_contains "index") (keyword_contains "NFP"))) (all) ) $} {$ next $}";
document.write(tmp.length);
</script>

Here's how I would like to use variables:
- I would like to be able to have very deep levels of variable nesting: My SiteTop contains HTML for the top of the site, which contains a variable for a navigation table, which contains variables for colors, and so on.
- I would like to be able to put CityDesk script inside variables and be able to have that deeply nested as well.
- I would like to put partial/incomplete CityDesk script inside variables and have it be evaluated "in the article" instead of before being place in an article.Example:

1. I have lots of authors on my web site.  Each author has a bio page.  I want to be able to generate a list of all articles by an author AND be able to change the listing style without making changes to each page (this problem also shows up when I go to change my boatload of index pages). 

2. What I have to do now is manually put this on each author's bio page. 
{$ foreach article in (and (not (keyword_contains "index") )
                      (author "Author Name")) SortAscendBy .headline $}
<DIV class=headline><A href="{$article.link$}">{$article.headline$}</A></DIV>
{$article.teaser$}
<P></P>
{$ next $}

Then, if I want style changes, I have to update EVERY page to have something, like say tables instead of divs.

3. What I would like to be able to do at a minimum is:
{$ foreach article in (and (not (keyword_contains "index") )
                      (author "Anne Sullivan")) SortAscendBy .headline $}
{$.AuthorArticleListingStyle$}
{$ next $}

where AuthorArticleListingStyle is
<DIV class=headline><A href="{$article.link$}">{$article.headline$}</A></DIV>
{$article.teaser$}
<P></P>

I cannot do this know because CityDesk does not know what to do with the author.whatever stuff because it is being evaluated outside of the loop (before the loop?).

4. What would make me really, really happy would to be able to place one variable on each author's bio page, with everything begin dynamically generated:
{$.AuthorsArticleListing$}

Where the AuthorsArticleListing variable is something like:
{$ foreach article in (and (not (keyword_contains "index") )
                      (author .author)) SortAscendBy .headline $}
<DIV class=headline><A href="{$article.link$}">{$article.headline$}</A></DIV>
{$article.teaser$}
<P></P>
{$ next $}

David Burch
Thursday, March 20, 2003

I also use variables quite heavily, and as I see it, they can devided into three major groups:

1) I use them for plain strings like colors, titles, copyright info and similar things that should not contain any HTML.
2) Simple HTML phrases, like <img ... > tags that I often use within the text (smiley images etc) that also should not have any extra HTML added, since it would destroy the layout.
3) More heavy HTML variables for things like top/bottom of sidebar, counter code and menu generation code.

As I see it, the variables window shouldn't have HTML capabilities. I think it will make it unneccecarily complex. Instead I would be more interested in having {$ include ... $} added to CityScript. That way, one could simply use the articles as HTML-capable variables. (Although it perhaps should be possible to mark an article "not for publish" then?).

The first category can be handeled by the (simple) variable editor, and perhaps the second one too. But for the third one, the article editor is better suited. (Why have one article editor, and one variable editor with the same capabilities?)

Having the possibility to group and sort the variables in the variables window would also be nice.

Another feature that would be nice is a menu popping up (á la Microsoft's IntelliSense in VS) when writing CityScript  statements, and not least variables to speed up the writing. I suppose I can live without this one though. ;)

Perhaps a bit more loosely realted to variables, but I don't like that the fields on the "Extras" tab is always HTML. I many times find my self wanting to edit their HTML code. And if I do the editing in the main editor and paste it back, the DHTML control messes it up when I take it back. =(

Henrik Jernevad
Thursday, March 20, 2003

Thanks! This is all very useful information!

Joel Spolsky
Thursday, March 20, 2003

Henrik,

So you're saying you'd want variables for plain text, and then something like a server-side include for bringing in an article.

You can sort of do that right now using the workaround Joel describes above - just put everything in a particular folder that isn't brought in by any loop, give it a template that doesn't have anything in it - and bring it in with a loop targeted at that file:

{$foreach 1 x in (filename "name") $}
{$x.body$}
{$next$}

Instant server-side-include.

Homesite also has contextual hints where if you open a tag, a little dropdown appears with valid properties.

That reminds me, a quick link to the CityScript Quick Reference in the help menu would be great.

--

This has me thinking... How many people here have ever used Dreamweaver Templates? They have an interesting "asset library." You just highlight something in the normal HTML editor, and tell it that you're making it an Asset and it deposits it in the library.

There have been times where I wished I could combine DW templates & CityDesk. DW template allow me to modularize the page, while CityDesk let's me dynamically generate my navigation.

It's much easier in DW, for example, to create a logo and use it across templates. Then updating the logo in the library updates it across all templates.

I guess the primary difference is that in DW it's not:

{$.header$}

it's

<!-- #BeginLibraryItem "/Library/Logo.lbi" -->

(html here)

<!-- #EndLibraryItem -->

so it actually shows up while you're editing the page. Updating Logo.lbi changes all the templates that use it immediately, rather than at parse time.

Just food for thought.

www.marktaw.com
Friday, March 21, 2003

One of the things I like about CD is the way you can use it to do things that probably would otherwise require javascript. Here, by way of example, is a "3-part bible lookup", which illustrates as well as anything why I don't want HTML editing for variables.

Variables :
bib1 = [<a href="http://bible.gospelcom.net/cgi-bin/bible?language=english&version=NIV&passage=
bib2 = &x=16&y=9" target=_blank><em>
bib3 = </em></a>]

Usage :
{$.bib1$}Mt 7:1-2{$.bib2$}judgement{$.bib3$}

The first bit is the reference for the lookup, the second the link text. This is about as close as you can get to macros for now, but it would be nice to be able to do something like :

{$.bibref [Mt 7:1-2] [judgement] $}

because it's cleaner, and you could use the parameters more than once in the expansion.

Michael Wild
Friday, March 21, 2003

I think many people use (or would like) to use variables as (parameterized) macro's. Such as in the bible-example: insert a link with a HREF and a text. {$bible_link(href,text)$} would give cleaner variables and templates than having it split up in 3 parts which don't make sense unless you see them together.

Adriaan van den Brand
Friday, March 21, 2003

I agree with "Adriaan van den Brand". Being able to have parameterized macros would be very useful and I think extremly powerful.

To marktaw: I actually think I use the foreach 1x-loop somewhere, but I really don't think that's a nice solution.
Replacing {$.variablename$} with three different {$$\}'s doesn't exactly make the page look nicer.


Another way, instead of using {$ include ... $} might be to be able to reference to specific articles using their magic name. Example; instead of writing

{$foreach 1 x in (filename "ArticleName") $}
{$x.body$}
{$next$}

you could write

{$ PTMFOG0000000032.body $}.

Or perhaps "body" could be the default property of the article, so it could be slimmed down to

{$ PTMFOG0000000032 $}

Henrik Jernevad
Friday, March 21, 2003

Of course, I'm going to rephrase the question: "Since we are going to vastly improve the functionality of variables, what features would you like to see?"

1. Variables are a different animal than articles. Rather than use an article window, I would suggest using only the text/html window.

Variables should be about site mechanics. The interface should be optimized for scripting and code.

If, for some reason, the facility of an article it is necessary, then call the contents of articles by using the filename system variable. Don't bastardize the variable functionality.

2. The creation of variable should be the job of the site designer or design team and should not be seen as something for the user to do. If the user has to routinely go in and tweak a variable, then the variable is poorly designed.

3. The use of variables can be only for the design team or for users, too. That depends on the variable and the context of use.

4. I use variables three ways -- global, sectional, and occassional.

5. Global: these affect the whole site and assist in maintenace based on change one, change all. Examples include:
-- meta tag information
-- copyright information
-- contact information

6. Sectional: these affect specific sections.
-- logo banners at the top of pages
-- menus

7. Occassional: I have a couple of variables that I would class as user variables (see above). For the most part, these add data into a template field. Judgement call: have a bunch of templates for specific uses, or one template and add user variables as the situation calls for it. For the most part, I choose the latter.

I started out using variables for formatting, but did not pursue this because the variable functionality is so primitive. Instead, I use a stylesheet in an html page.

If the variable module worked like the template module, I would reconsider this decision. Same goes for menus (I call the contents of an article). Reasoning: keep functions separate. Site mechanics in variables and templates, content in articles and pages.

No matter what, I think it is VERY important that the UI be clear and provide guidance in how FogCreek thinks variables should be used.  As I mentioned above, variables should be treated as behind-the-scenes mechanical functions and should not be treated like articles.

If variables are given the same interface as articles, two things happen. First, the UI is implying that variables are out-front in the same way articles are. Second, when the designer is whipping through tasks, there is a chance for confusion because the visual clues which differentiate functional windows is missing.

In the same way that you purposefully don't provide certain features in FogBUGZ, you should take the same approach to CityDesk and variables.

Amos
Saturday, March 22, 2003

I just want something like the non-HTML ("normal") editor. Variables should be treated as "raw" HTML (this is how I use them). I have a variable for each colour I use in my CSS. I have a variable for my XHTML-and-CSS-validation images and my "Made with CityDesk" image. I have a variable for my banner (the image across the top of my website).

I want my variables to represent things that I can insert "whole".

I'm not at all interested in an HTML editor for variables.

-austin

Austin Ziegler
Saturday, March 22, 2003

I am currently adding what I am calling a "Travel Planner" to all the destination pages of my web site.  This is basically a bunch of "Related Articles" links with the articles being those of businesses in the destination area.  This will be a service to people needing those services while visiting the destination, free me from answering e-mails about "Where should I stay in ___?", and maybe even generate ad revenue.

What I need is a way to say get me all the articles with keywords: lodging, businessdirectory, and destination. 

What I have to do now is manually update each article with the same CityDesk script, changing the destination for hundreds of articles on the site.  It would be great if there were some way to make automatic use of a DESTINATION(CityName) keyword already in the keywords field.  Failing that, I would like be able to have one variable and pass the destination as an argument to be using the the foreach loop.

Or I would like something better and easier.  I don't really know the solution to this problem, but I am letting you know how I am using the variables under the "Tell me what you want, not how to do it" rule.

David Burch
Saturday, March 22, 2003

It seems to me that many people are using variables to actually store CityDesk scripts.  Would it make sense to leave variables pretty much as they are, with better sorting and access and add a container (with much more functionality) and include mechanism  to store and reuse scripts?

David Burch
Saturday, March 22, 2003

I also use a number of variables for Unicode entities (e.g., {$.osQuote$} : &#8217;, {$.csQuote$} : &#8218; em-dash, en-dash, en-space, double quotes, etc.).

If there's a way to make this easier (without variables), that would be good.

-austin

Austin Ziegler
Saturday, March 22, 2003

I use variables:

-to define the html for a css stylesheet, which I include in the header of every template--I do not like separate stylesheet files,a browser visiting my homepage should only have to download one file. The Return button behavior is a pain when editing this variable

-to define a short snippet of HTML as a separator for my weblog, which is otherwise clumped by date. I edit the raw HTML in text mode, which is how I prefer it, then on my weblog I can type "This is what I had for lunch {$.sep$}I just bought this book{$.sep$}Isn't minutae boring?"

-to define a common footer

I prefer working with raw text for all of these, and generally would prefer if Return did not dismiss the variable editing dialog.

R Tate
Saturday, March 22, 2003

There is a fundamental confusion here, I think.  Joel has named these "variables," but I think this is the source of a problem.  What people are really using them for is to define SITE CONSTANTS.  This is because that's all you can do with them: set them.  They are read only. 

In my opinion, they should be renamed "Site Constants." 

Then, a real, live, VARIABLE type should be added, which can be written and read.

I use exactly ONE "variable:" homeURL, which I can reset to move the site to a different root.  This is required if links off the root must be "hard-coded."

All other formatting is accomplished with style-sheets.

All items, such as copyrights, which must be included, are done with Articles that are inserted via the standard CityDesk mechanism.  This provides a standard UI for maintenance.  Page generation is slower, but only those pages that change have to be generated and copied to the server.  If they had to be dynamically generated for each page view, this would not be an acceptable solution.

I find that "variables" are not useful, as a page cannot set a "variable."  If there were a real variable type, a page COULD set a variable, and a template could take advantage of this and read the variable to establish what Articles to retrieve.  Because it cannot, and because there is no mechanism for a template to know what page it is generating, I have to use CD to generate PHP pages that does post-processing.

I encourage Joel to divide the concepts before things get out of hand.  It is good to have BOTH constants AND variables.

Joel Finkel
Monday, March 24, 2003

I agree with Joel Finkel. These are not variables but constants.

I also think an include script statement will remove the need for using html in variables/constants.

Thomas Eyde
Saturday, March 29, 2003

Feature Request:

I would like the ability to allow end-users to insert variable content from a pull-down list of variables names on the toolbar.

CityDesk scripting has a very strange syntax to both programmers and non-programmers.  Having to type {$.VariableName$} instead of selecting VariableName from a list which inserts {$.VariableName$} (or the contents of {$.VariableName$}) leads to many errors and increased customer support.

David Burch
Monday, March 31, 2003

*  Recent Topics

*  Fog Creek Home