This document contains a few working demos, together with some light documentation to help get you started using Dummy. It also makes a suitable test page. If you can get it to operate without error then you're ready to start using it in your own project.
29 |If you're unclear as to why you'd want to do this in the first place, then head over to the project page, or check out the README.md file included with this download.
30 | 31 |You'll need a development environment running Apache and PHP compiled with support for GD. Such an environment is provided out-of-the-box by Mac OS X. Alternatively, there are many MAMP and WAMP binaries available to both Mac and Windows users respectively. These are easy to install and configure and a good way to get started if you're on unfamiliar ground.
37 |Move the main /dummy folder to the root level of your web project, and make sure any .html documents in which you plan to use Dummy are renamed with a .php extension (or enable the .htaccess file in dummy/extras to continue with a .html file extension).
Make sure that any document in which you want to use Dummy has the following code on the opening line.
45 |
47 | <? require_once("dummy/dummy.php") ?>
48 |
49 | Finally, make the cache folder located at /dummy/cache writable by your web server. If you see an image immediately below this block of text, it's working. A new image should appear every time you reload the page.
57 | $filename exists and seems to be writable."; 61 | } elseif (file_exists($filename)) { 62 | echo "$filename exists but it isn't writable by your web server. Please make it writable."; 63 | } else { 64 | echo "$filename does not seem to exist. Create it and make sure it is writable by your web server."; 65 | } 66 | ?> 67 |
68 |If things are not working for you here are the first things to check...
74 |Double check that the path to /dummy/dummy.php in the top of your document is valid. This is the machine path (not the web path), so you might need to change it if you're using Dummy in a subfolder.
Make sure the cache folder located at /dummy/cache is writable by your web server.
If for some reason you're not using a virtual host, or you can't include /dummy on the root of your project, check the very first line of /dummy/dummy.php and make sure the path is valid. This sets the web path to images generated by Dummy.
The use of a virtual host for your web project is not only a solid best practice, it also makes Dummy a zero-config affair. For Mac users, Patrick Gibson's virtualhost.sh script for creating and managing virtual hosts is an excellent place to start. But there are lots of command line and GUI based alternatives across all platforms.
If you prefer to keep your document file extensions as .html, enable the file located at /dummy/extras/optional.htaccess file by removing the "optional" prefix and moving it to the root of your web project. Doing so will ask Apache to parse HTML documents as if they were PHP.
The ability to select, manipulate, and insert different assets into your front-end project is a key feature of Dummy. All of the assets available to Dummy live in a folder located at dummy/assets/. It's a good idea to poke around in here and see how things are structured. The simple syntax used to request different assets relates very much to the structure of this directory.
93 | 94 |Dummy makes it easy to insert random strings of Lorem Ipsum that correspond to commonly needed lengths and formats. For example, the following snippet of code will produce a random string of Lorem Ipsum approximately the length of a headline.
97 | 98 |
100 | <? dummy("text@headline") ?>
101 |
102 | The exact result will be different every time you reload your document, but it should look something like this...
105 | 106 |The following table is a catalog of Dummy's default assets, the snippet of code used to insert the asset, and a sample of actual output.
111 | 112 || Objective | 117 |Dummy Code | 118 |Output | 119 |
|---|---|---|
| Headline | 124 |<? dummy("text@headline") ?> |
125 | 126 | |
| Teaser | 129 |<? dummy("text@teaser") ?> |
130 | 131 | |
| Short Teaser | 134 |<? dummy("text@short-teaser") ?> |
135 | 136 | |
| Long Teaser | 139 |<? dummy("text@long-teaser") ?> |
140 | 141 | |
| Item | 144 |<? dummy("text@item") ?> |
145 | 146 | |
| Date | 149 |<? dummy("text@date") ?> |
150 | 151 | |
| Time | 154 |<? dummy("text@time") ?> |
155 | 156 | |
| Time ago (relative) | 159 |<? dummy("text@time-ago") ?> |
160 | 161 | |
| Author | 164 |<? dummy("text@author") ?> |
165 | 166 | |
| Username | 169 |<? dummy("text@username") ?> |
170 | 171 | |
| City | 174 |<? dummy("text@city") ?> |
175 | 176 | |
| Paragraph | 179 |<? dummy("text@paragraph") ?> |
180 | 181 | |
Hint: Inside of dummy/assets/text/ you'll find a directory full of flat text files. These are the basis for organizing different text formats used by Dummy. You can edit these or add your own as you like.
185 |Dummy makes it easy to crop and size placeholder images on the fly. It ships with a starter pack of high-quality, newsworthy, Creative Commons licensed images, but like other assets it's easy to edit or expand these according to the needs of your project.
191 |The syntax for requesting an image is flexible. In a very basic example, you request an image with specific dimensions...
192 | 193 |
195 | <img src="<? dummy("image@480x320") ?>" />
196 |
197 | ...and the following is returned:
200 | 201 |You can specify exact pixel dimensions or just an aspect ratio. You can also combine these parameters. For example, you can choose to specify just the width together with an aspect ratio. Dummy will return the path to an image that conforms to both requirements.
206 | 207 |
209 | <img src="<? dummy("image@640x,16:9") ?>" />
210 |
211 | Returns...
214 | 215 |Note: Dummy returns a URL path to an image, not the HTML needed to embed it.
218 |The following table provides some clues as to how you can structure your image requests.
221 | 222 || Objective | 227 |Dummy Code | 228 |Output | 229 |
|---|---|---|
| 100px square Classic. Square. | 234 |<? dummy("image@100x100") ?> |
235 | "> | 236 |
| 100px square (Part II) A rather pointless way of generating the same result as above. Proving a point here. | 239 |<? dummy("image@100x,1:1") ?> |
240 | "> | 241 |
| 16:9 With a height of 200px. Pixel dimensions and aspect ratios must be separated with a comma. | 244 |<? dummy("image@16:9,x200") ?> |
245 | "> | 246 |
| 16:9 (Part II) Same as above. It doesn't matter which order you specify ratio or pixel dimensions. | 249 |<? dummy("image@x200,16:9") ?> |
250 | "> | 251 |
| 3:2 The Photographer's aspect! We'll ask for assets from a specific subdirectory of ‘dummy/assets/images/’ here to improve the odds of getting a suitable image. | 254 |<? dummy("image/landscape@3:2") ?> |
255 | "> | 256 |
| !Avatar Subdirectories of ‘dummy/assets/images/’ that begin with a ‘!’ are exempted from normal random (and recursive) selection. You have to target them specifically. This is good. | 259 |<? dummy("image/!avatar@150x150") ?> |
260 | "> | 261 |
Note: When specifying dimensions, either as an exact pixel measurement or as an aspect ratio, describe the width first and height second (Width x Height).
265 |The basic model for how Dummy selects image assets is semi-random and recursive. It begins looking for assets on the root level of "assets/images" and drills down, only ignoring sub-folders with names that begin with a ‘!’. Dummy also works in the background to track which image was most recently selected, in order to minimize the odds of inserting the same image in succession or in close proximity.
268 |Inside of /dummy/assets/ads you'll find a host of folders representing many of the popular formats as defined by the IAB. The dummy code used to request and insert an ad follows the now familiar model.
273 | 274 |
276 | <? dummy("ad@120x90") ?>
277 |
278 | Returns...
281 | 282 |Note that a request for an ad returns a pre-formatted block of embed code containing an ad, as opposed to just the URL path to the ad (as is done with images). The reason for this is that we often need blocks of repetitious, ancillary markup to surround ad placements, as is the case with regard to advertising in the Adobe® Flash® format.
287 |The default embed code for both standards compliant image based ads and ads in the Flash format can be found on the root level of /dummy/assets/ads in the form of two files — image.embed.php and flash.embed.php respectively. You can override the use of these defaults by placing an edited copy of one or both of these files in the folder of the format you wish to override.
288 | 289 |The folders containing different formats are also used to specify their dimensions (WxH). Dummy parses these folder names and interprets them as variables, which in turn can be used to set the width and height values of ads as they are parsed into the embed code. If you don't feel it necessary to pass these values to your embed code, you're free to add new formats in folders and name them however you like — just remember to create a custom embed for these formats.
290 | 291 |You may find it useful to enable or disable the insertion of Flash format ads under different testing scenarios. There is a global preference toggle in the top of dummy.php for controlling this. The default is disabled.
292 |The ability to insert randomly selected assets into a layout is great, but it's Dummy's simple logic for controlling probability and creating loop ranges that make it possible to flesh out highly variable, asset rich layouts with very little code. The basis for this logic is contained in a function called dumb_luck.
298 | 299 |A basic building block of Dummy driven layouts, dumb_luck can be used to influence the probability that something will happen when the document is rendered. This helps answer the age old question, “What does this layout look like with or without X ?”, where X could be an image, a special announcement, or a block of JavaScript that triggers some other chain of events.
302 | 303 |
305 | <? if (dumb_luck("50%")): ?>
306 | There is a 50/50 chance of this happening.
307 | <? endif ?>
308 |
309 | Jazz up your dumb_luck logic with fallback or alternative outcomes using standard PHP if/else statement structure.
312 | 313 |
315 | <? if (dumb_luck("95%")): ?>
316 | Pretty damn likely to happen.
317 | <? else: ?>
318 | This is a lot less likely.
319 | <? endif ?>
320 |
321 | You can also nest dumb_luck logic as needed, to test and explore more complex outcomes.
324 | 325 |
327 | <? if (dumb_luck("50%")): ?>
328 | <? if (dumb_luck("50%")): ?>
329 | Heads
330 | <? else: ?>
331 | Tails
332 | <? endif ?>
333 | <? else: ?>
334 | <? if (dumb_luck("33%")): ?>
335 | Rock
336 | <? elseif (dumb_luck("33%")): ?>
337 | Paper
338 | <? else: ?>
339 | Scissors
340 | <? endif ?>
341 | <? endif ?>
342 |
343 |
344 | For the record... HeadsTailsRockPaperScissors!
345 |Dumb Luck's loop range takes whatever content you place inside of it and loops it within a range of two numbers that you specify. Inside of the loop range above, a single request for a 35x35 pixel thumbnail.
356 |Loop ranges make it possible to generate massive amounts of variable content very quickly. In the example above, there are two bits of Dummy code working together. A dumb_luck loop range of 50-100, and inside of that loop range, a single request for a 35x35 pixel thumbnail.
359 | 360 |The thumbnail will be rendered no less than 50 times, and up to 100. The Dummy code used to achieve this is compact and human readable:
361 | 362 |
364 | <? while (dumb_luck("50-100")): ?>
365 | <? dummy("image@35x35") ?>
366 | <? endwhile ?>
367 |
368 | Loop ranges are built on the same dumb_luck function used to control probability, only instead of passing in a % value we pass it a range of two numbers separated by a hyphen. These two values define the minimum and maximum number of times the loop should continue. In the example below, we ask for between 5 and 10 instances of a list item containing a headline.
371 | 372 |374 |
Note that the PHP syntax used with dumb_luck requires “WHILE” in association with loop ranges.
381 |The result is a simple UL containing between 5 and 10 list items:
384 | 385 |Taking the same list used in the previous example, imagine we needed to see how it would look with some of the items linked some of the time. To achieve this we'll nest some probability logic inside of our loop range.
398 | 399 |401 |
Though the exact number will change every time you reload the page, roughly half of the items in the following list will be wrapped in a link. It's a very basic example, but one that uses all the core features of Dummy.
414 | 415 | 416 | 419 | 420 |When used together, asset generation, probability, and loop range logic can create highly variable layouts with very little effort in code. This makes it possible to quickly test how the change of an item, attribute or parameter in one place propagates on a range of different scales. It can provide new insights on the performance or design efficacy of your work at the earliest stages of a project, and every time you reload the page.
421 | 422 |424 |436 |<? dummy("text@headline") ?>
425 | <? if (dumb_luck("25%")): ?> 426 |<? dummy("text@long-teaser") ?>
427 | <? endif ?> 428 |By <? dummy("text@author") ?> | Published <? dummy("text@date") ?>
429 | <? while (dumb_luck("3-8")): ?> 430 |<? dummy("text@paragraph") ?>
431 | <? endwhile ?> 432 | <? if (dumb_luck("75%")): ?> 433 |Related Story: <? dummy("text@headline") ?>
434 | <? endif ?> 435 |
An example of a simple article 3 to 8 paragraphs in length, with optionally appearing intro text and related story elements.
437 |There are a few unfinished features in Dummy that remain too fluid to document, namely the dumb_question function for reading and reacting to loop position, URL variables, and URL segments. More info to come on those when they're done.
445 |In the meantime, follow the project on GitHub. Your ideas and contributions toward improving the code are welcome.
446 |