In this chapter we introduce the ideas that make Patapage. We try not to be too technical, but we assume that we are talking to users that are web site designers / builders, and hence familiar with the notions of web site, web page, link, HTML. We’ll touch several ideas related to web development which are related in different ways to site design and development.

If you find what is written here too abstract or technical, read first the next chapter, 2. Example applications, where we present several usage examples: we show how to use Patapage as tool when building web sites.

If you are familiar with the concepts and are looking for a user guide, go to 3. Patapage.

1.1 Improving a site by pasting a script

Patapage is a way of adding services to web sites (also static ones) in a most simple way: just by adding buttons and links. There are buttons for socially contributed contents, like adding a wiki-like layer to your pages, and also comments, image galleries, contact forms, rating, retweet, Google or Twitter searches, windows on other websites, annotated feedbacks, and so on.

By relying on this service, you are avoiding any additional kind of server maintenance, and getting some nicely designed and customizable additional layers on your site. All this in an unobtrusive, simple way.

Anyone who is familiar with adding Google analytics or Twitter gadgets on their site will find Patapage simple to use and in line with the current evolution of the web.

1.2 First impressions: a short story

Patapage is a tool that can drastically reduce the effort needed to build services for supporting a web site’s community, without impacting the web site design and structure. But few people currently appreciate this: let me tell a short story.

One evening I had dinner with a very smart friend, developer and consultant. He told me

“Tell me about Patapage! The small guy logo is just great. Generates those docked buttons…”

He had had a quick look to the site, and… missed the aim of the software. He is not alone: we are finding that this is what happens to many visitors of the site: after the first wow effect, visitors believe they got what Patapage is about:

adding pretty docked buttons on your pages pointing to external services, to which some behavior is delegated

This is a partial picture of what Patapage can do as a service for a web site creator. In this chapter we show the full picture.

In the case of my friend, I started explaining him that yes, delegation to an external service is one of the basic ideas that makes building richer web sites easy and quick, but Patapage is useful because “external” content can be integrated page by page in the hosting site – and you are never leaving the site where you started from. This makes say building a site for a conference, like the one we built for Developers in Florence, really fast: once we had built the static page, like this:

Figure 1 The “Developers in Florence” page before Patapage – basic information

then we just created an account on Patapage for the domain and added contacts, feedback, discussions, filtering or relevant tweets and delicious tagging, and more, as in the following picture– see it in action here: http://www.open-lab.com/diff01. Ready to publish!

Figure 2: The same site made interactive

I explained this to my friend, and I saw a more and more surprised look on his face, as he realized the simplicity and power of the tool, and that he could use it immediately for some of the web pages he had to publish.

Consider that the example I made above is one of the simplest usages: a deeper mapping of your needs is done by integrating Patapage’s functionalities in the body contents of your pages, using your own styled links instead of docked buttons, and even keeping parts of the contents of your pages generated by wiki-like parts, maintained with Patapage. You can delegate to Patapage all the functionality needed to motivate, support and maintain a community on your site: no development is needed.

“So –my friend suggested – I could build a page-by-page help system just by pasting a script on my site’s footer?”

Yes, exactly. Just like when you replaced your CMS statistics with Google Analytics – the effort is the same.

1.3 Your first impression from the demo

If you go to Patapage’s home page (http://patapage.com), you can immediately test any of your favorite web sites as they could be “empowered” by Patapage:

Getting:

Now this is nice but can be highly misleading, as it seems that all Patapage provides is only some pretty docked buttons – wrong.

There are so many improvements that your could get using Patapage – without changing the web site technology, layout or design. It’s not just docked buttons!

1.4 Your site structure

What is the relationship between your site structure and Patapage? What parts of your site contents and functionality can you build with Patapage and what not?

The set of pages of your site and the links between them defines the “structure” of your site.

Mathematically: Pages and links constitute a directed graph.

Your site will have internal links that bring from one page to another and links to external sites and resources. In the simplest case, both your pages and links between them will not be built with Patapage: you will build everything with simple static HTML pages and links. Once this done, the site’s core is defined, and you can add more interactivity and functionality with Patapage.

Patapage can enhance single pages of your site, making them interactive, and can make also the page interact between them and share contents and contributions.

What you obtain in this way is a site indexable and easy to maintain. Gone is the time where you either built a static site or you “developed” one by web application programming.

Maintainability of a site or application is often proportional to the amount of coding you have done to build it; this way, you’ll keep it at a minimum.

1.5 What is a “dynamic site”?

From Wikipedia:

A dynamic website is one that changes or customizes itself frequently and automatically, based on certain criteria.

…

Purpose of dynamic websites

The main purpose of a dynamic website is automation. A dynamic website can operate more effectively, be built more efficiently and is easier to maintain, update and expand. It is much simpler to build a template and a database than to build hundreds or thousands of individual, static HTML web pages.

From http://en.wikipedia.org/wiki/Web_site#Dynamic_website

What is meant by “certain criteria”? And what by “automation”? These are in fact vague terms. Today “certain criteria” can also mean contributions coming from sources external to your website, being people discussing the topics you present, Wikipedia entries updated and relevant to your topics, and more. With Patapage you can connect your site to external changes, and make local changes and discussions possible, in a way which could hardly be simpler.

This way your site will evolve in time just as much as the web to which it is connected.

The main point here is that what is “happening”, concerning your web site topic, more and more likely is happening “outside” of your web site. The ideal automation would be that the site somehow “keeps in contact” with what is happening outside of it, and Patapage provides a very simple way to get that.

1.6 The problems of “classical” Content Management Systems

You have your beautifully designed static site. You can express fully your creativity with it, using html, JavaScript and Flash. Maybe one day you add some PHP functionality. You keep changing, adding, hacking and improving here and there.

But then one day somebody explains you the "content management system" (CMS) idea; all you wanted was a way to put news on the site, but somehow you get "converted", and you make a tragic mistake: you set up a content management system, pay for the server and the software, and after a hard fight it almost works. Then you try to convert your beautiful web site in dynamic pages, and there the pain starts; what was before simple and immediate becomes cumbersome if not impossible. The flexibility in design and updatability which you have in simple HTML is now constrained by templates and hard coded layouts.

Also the site becomes much slower, one day the database crashed and you had to rebuild everything...: Something's wrong.

Patapage is a revolutionary alternative to all this; an alternative compatible with existing web sites, which allows you to add page-specific dynamic content even if your site is a simple static site. We take the pain out of managing contents of beautiful web sites.

Patapage is perfectly compatible with the idea that web contents should be "pluggable": you just have to progressively add features from Patapage on the same layout.

1.6.1 Limits of Patapage

Patapage can’t do everything. It is an additional tool for people that are building sites with an HTML editor of some kind or a CMS or an application framework; the core site, pages and structure, is built externally to Patapage.

The core of the site should not be built with Patapage, though with the “content in place” functionality, it could. Patapage is a tool to get more power while keeping things simple, and overusing it will lead to more complexity.

1.6.2 Using both a CMS and Patapage

When we started building the “Developers in Europe” web site http://devineu.eu

we had a long list of requirements; in particular we had to have the possibility of adding new interviews and getting all the indexes and list updated automatically. This is a task that “classical” CMS handle perfectly, so we used our own CMS (home built: it’s called Webwork).

But for other ends, we used Patapage, for example:

Enabling comments and feedback on the pages, as in the picture:

Showing Twitter feedbacks for the site, as in the picture:

1.7 A short introduction to web services and mashups

Patapage can be understood as a refined “mashupping” service. We’ll take that perspective in this section.

This section is quite technical. You can skip it, and live happily ever after.

The term “mashup” is quite popular among web developers. This is the Wikipedia definition of mashup:

In web development, a mashup is a web page or application that combines data or functionality from two or more external sources to create a new service. The term mashup implies easy, fast integration, frequently using open APIs and data sources to produce results that were not the original reason for producing the raw source data. An example of a mashup is the use of cartographic data to add location information to real estate data, thereby creating a new and distinct web API that was not originally provided by either source.

http://en.wikipedia.org/wiki/Mashup_%28web_application_hybrid%29

And this is of mashup enabler:

In technology, a mashup enabler is a tool for transforming incompatible IT resources into a form that allows them to be easily combined, in order to create a mashup.

http://en.wikipedia.org/wiki/Mashup_enabler

Why mashups are useful for your site? You can improve your site’s services drastically without yet more code to maintain.

Mashups are today used either in widgets supplied by online service providers, or built by hand by developers for particular sites and pages. Thinking about generalizing and simplifying the usage of mashups and the creation of web widgets, there came the idea of creating a dedicated online service, Patapage. Now mashups are mostly used by developers, in particular, JavaScript developers. A nice and typical example is this one:

How to build a personal mashup page with jQuery: http://theezpzway.com/2009/5/1/how-to-build-a-personal-mashup-page-with-jquery :

and the result is this: http://enriquez.github.com

where we see the date collected and displayed. Notice that this is all done purely in JavaScript on the client, also using Yahoo Pipes service (http://pipes.yahoo.com/pipes/); but this requires some development and maintenance, and the server side service has to be already available; you cannot build your own service without installing and maintaining your own server. Another widely used option is to use the web service provider widget (“web widget”), but the style is more or less fixed. Like adding a widget on your site with “recent tweets”. All this is fine, but is limited, and may lead to inconsistent graphical results, and makes you lose control, and gets you to use a set of tools that changes all the time.

While mashups and web widgets support the latest interaction techniques, they loosen control of the user / web site interaction, and also make it problematical to keep a consistent design. Patapage solves these problems, by providing an environment for embedding mashups and customization of additional layout.

1.7.1 Our idea

Our starting idea was… why not give even more power to site builders on the client side by relying on a unique, simple service, acting both as direct content manager and as “proxy” for other services? The fact that Ajax calls allow to add and call Java scripts on say a button click to an existing, fully loaded page, and then by making cross domain requests it becomes possible to add contents to (over) the calling page, opens a world of possibilities, which up to today has been used only by developers of both client and server side code, by low level access to such features and then lots of hand coding.

Couldn’t it be easier? Couldn’t the HTML designer be spared of (re)building specific client readers and server-side services, and focus on just integration and building a beautiful and friendly site? And even if you are a server-side developer, why not delegating web site content building to a third party, and focus on your main activity?

Why use mashups only to add RSS aggregation, pull data from social sites and multimedia contents? Why not use for any kind of dynamic contents? Why use it in blogs and not web sites? The structure of web site is more complex, and the services needed more refined, at times, but that’s no obstacle to the idea.

Also in case of hand built integrations, the graphic quality of the integration is often not at the same level of the originally designed site.

This is where we started thinking about a new online service, and then started building it up. In mashup terms, we started building friendly data sources to be called and used on button and link clicks; then we standardized even the buttons and links, so that the web builder has just to paste the button script on the page, and gets immediately fully working buttons, links and associated services.

Since we had the service up, almost every day a new possibility of a button comes up, as the sum of serving both the client side JavaScript and the server side content, or proxy to contents, opens a lot of possibilities. See in the side picture just the first suite of buttons.

More are being added, like Picasa integration, custom designed forms; the existing ones are being extended, like the Wiki-button will allow creations of new pages from links, like Wikipedia.

What superficially looks like a single functionality, like adding a wiki-like button (“PataWiki”), actually adds to your web page a layer of dynamically updatable content, by both the site maintainer and site visitors (if that is what is wanted). This could be a “help” page, contributed contents, a “more in depth” presentation, a “buy now” page (we’ve seen it online used this way already), a way to publish news, …

Each button / link you paste in your pages is associated with a “contentKey”, which the designer can set by hand: this way the same mashup / widget combination can be used across the entire site, on a single page, or shared across a specific group of pages. This is flexibility that usual mashup on blogs don’t need, as these are basically single paged, but is a necessary extension for using mashup effectively on web sites.

We also developed a web based configuration of buttons and opened windows, which allows setting of style, dimension and layout. This is what you had to do by writing code and HTML by hand when displaying the contents of mashups – before Patapage :-). Of course if the designer wishes, she can customize the layout of the buttons integrating in the existing layout, as done in this example.

1.7.2 Patapage button-relative security

Another recurring problem when adding the possibility of visitors contributing and commenting your pages is that of spam, moderation, e-mail verification and in general of security. Like for example if you enable moderation, you have both to reassure users about their contribution, manage the incoming list to be moderated, notify on approval, etc.: imagine having this by just pasting a little script on your static site instead of configuring a CMS to do that, or worse, programming it from scratch! And you should be able to do this differently for each link or button, if you wish so.

The resulting application is not only a mashup enabler as defined at the beginning, but also a tool providing mashups of all sorts ready to be used.

So we are covering the problems of layout, contents, social contributions, notifications, security… all typical problems traditionally requiring installing your own CMS. This way we are empowering links on the web pages of a site that is preserved as it is, with all its style, effectively progressively making classical CMS’s site development look like stone-age site building.

1.8 From Cinderella to Princess

A pretty good site is probably not enough in 2010. As more web applications get used online, people expect to find in any web site functionality and quality similar to that of web applications that they use in everyday activity. The web can be used to get in contact, to get feedback with an ever wider audience – grannies are capable of using Facebook.

The effect you can obtain by just adding a couple of embedded services to your site can be quite surprising.

1.9 Progressive enhancement

Progressive enhancement is a strategy for web design that emphasizes accessibility, semantic HTML markup, and external stylesheet and scripting technologies. Progressive enhancement uses web technologies in a layered fashion that allows everyone to access the basic content and functionality of a web page, using any browser or Internet connection, while also providing those with better bandwidth or more advanced browser software an enhanced version of the page.

From Wikipedia, http://en.wikipedia.org/wiki/Progressive_enhancement

Patapage is perfectly compatible with this idea: if you add dynamics with Patapage, it will be an additional layer. What if the JavaScript engine of the visitor does not work? What if the service is down? What if the customer is visiting the site with some limited device? What if…? There is always your basic site content and functionality – and that will always work.

With Patapage you delegate functionality, while keeping complete control. Patapage is not a universal tool, and intentionally so. The core of the buildup of the site is done with your own tools, with your preferred simple HTML editor.

Recap

Patapage is a completely new way to add functionality to web sites, in a way where you are keeping control. You can add functionality one piece at a time, never bringing down your site, without breaking your design.

Patapage will be loved by people frustrated by CMS. Patapage will be loved by people that put design at the center of web development. Patapage will be loved by people that want simple solutions. Your site can keep evolving, can keep collecting and interacting with all the information sources out there without becoming a complex application. It will remain a simple set of HTML pages.

Patapage is the unanticipated solution to a host of web problems which usually require effort to solve, and the usual solution requires effort to maintain – Patapage doesn’t.

Figure 3 Patapage is at the intersection of:

Figure 4 What is patapage

Venn Diagram

2. Example applications

In this chapter you will find examples of real sites and needs where one may use Patapage. We describe how the need is met, without entering in technical details. For the latter, read next chapter, 3 Patapage user guide.

2.1 The demo site: http://patapage.com/demo

The demo site presents first a site draft design, and step by step shows the various Patapage functionalities. Going through it is a great way to see Patapage in action.

Figure 5 Draft of site

The site is about an imaginary musician, Alice Lin. From the draft image above and at the URL

http://patapage.com/demo

you can see the planned sections. It has to be taken into account the target user, who in this case will likely be young and familiar with “social” web technology. Patapage can be a perfect answer to this kind of interactivity needs.

The final result is this page: http://patapage.com/demo/fullSite.jsp

Figure 6 Resulting site

For example by clicking on discography you get:

This is a content which can be managed by the site editor (or by the community) in place:

If you are impatient to try this out, you can skip to the user guide (3 Patapage user guide).

In conclusion, in the demo you see a perfectly “static” site, made just of HTML and images, turned into a powerful reference site, capable of interacting with a large community of “fans”, obtained with a minimal effort: a Patapage account, some button configuration, a few ”paste” and FTP. J

2.2 More interaction with users: http://pupunzi.com

Pupunzi.com is a website where Matteo Bicocchi (one of Patapage developers) publishes great jQuery components. He needed a way to have more interaction with his community.

So he simply added two docked buttons: one for posting comments on the site, another which searches for his last blog post on his blog and presents it. A third button from Patapage eases retweeting the page to others.

In this way he has automated updates on the Pupunzi site when posting on his blog. He interacts “safely” through comments (Patapage gives him moderation), and monitors retweets. All done on a simple, static site, by simply pasting the buttons.

2.3 Presenting a social event: http://www.open-lab.com/diff01

For the “Developers in Florence” event we wanted to quickly create a reference page, a simple static one, where people could have several ways to interact.

We used several Patapage functionalities; let’s see them one by one:

Button	Image	Usage	How it was generated
		Gives visitors a direct way to provide feedback on the event.	A docked button for comments with moderation enabled. Opens a “window” (a floating div) on top of the page.
		A wiki content (editable only by the site owner in this case) that provides the links to the slides of the speeches from the event.	A docked button for a wiki like content enabled with write enabled only for site admin. Opens a “window” (a floating div) on top of the page.
		A filter on Twitter showing the recent Tweets relevant for this page.	A docked button with a filtered search. Opens a “window” (a floating div) on top of the page.
		A tree like discussion support, collecting suggestions for next event.	A docked button opening a comment tree. Opens a “window” (a floating div) on top of the page.

Button	Image	Usage	How it was generated
		The speakers of the event marked in Delicious some urls where “in depth” information about the event topics can be found. This buttons searches there.	A docked button with a filtered search. Opens a “window” (a floating div) on top of the page.
		A textual link opens a contact form. This shows that you don’t necessarily have to use the provided docked buttons.	A link which opens a “window” (a floating div) on top of the page containing a form.
		A textual link opens the Google map remaining above the current page.	A link which opens a “window” (a floating div) on top of the page containing an external web site page.

Again, we have all this functionality in a very simple static page.

2.4 An intranet in five minutes: Open Lab’s intranet

I’ve just won the latest foosball match of Open Lab’s tournament. Our intranet, which is actually a static content on the Teamwork web application (http://www.twproject.com), is built with Patapage. This means that in order to update the foosball scores, I just have to go to the page:

In this case the intranet page contents are really managed as a wiki: anybody can edit them. In this way we ease updates, and it’s more likely that the reported information is updated. Now

I just rollover with the mouse on the results part, the edit button appears, I click it:

A full HTML editor is now ready, I update the scores, save, and the pages is immediately updated (without even a single reload):

Here we see a first usage of “in place” contents: the contributed and/or backoffice edited contents can now be shown directly inside the calling page. Cool, no?

Notice also that we’ve put a “discuss” link lets you post comments:

In the case of an intranet you may relax the moderation requirements; consider that in all cases the complete history of changes is preserved – Patapage does it automatically.

2.5 A nursery school site: pictures! http://www.lemaghemago.it

In this case the school wanted to have a way to frequently and simply update pictures on the site in order to show the ever-changing activities. As they were already familiar with Flickr (http://flickr.com), they just needed a couple of buttons pointing to the Flicker gallery:

Simple and effective.

2.6 Commenting startup interviews

Open Lab maintains a web site dedicated to interview to European startups, “Developers in Europe”, http://devineu.eu

Each startup interview has a dedicated page /URL, for example

http://devineu.eu/allInterviews/broadcastingViaTheWeb.page

we wanted for each interview to enable the possibility of commenting it “in place”, a bit like a blog post can have comments.

Given that each interview is on a different URL, it took a minute: we just went to Patapage, chose as type “comment”, picked “the content is unique to each page” with “Remore page parameters”, and a few more choices:

Pasted on the site, and that was it, here is the end of the interview:

And the interviewed, how does he / she get notified of new comments? It won’t be the site owner notification, because the owner of the site (actually, the Patapage account) is Open Lab, and the interviewed is different for each interview, does not manage the site. Well, to be notified its very simple, both for the interviewed, and also for those who are commenting: just open the RSS feeds of the interview page:

And subscribe to “Comment interview”. J

2.7 A site on high quality Tuscan olive oil

The customer needed to publish and easily update three photo galleries on a static site:

http://www.laudemio.it/site/culture/index.html

The beauty of the pictures enhances the site… . All done in a few minutes.

2.8 A vegetarian restaurant

A way to turn your restaurant site “social” quickly: see this simple example, with just two buttons and moderation:

http://www.il-vegetariano.it/

2.9 Using Patapage on a blog

Can Patapage be used on a blog? Well, it depends on the kind of control you have over the composition of blog pages – whether you can “paste” JavaScript in pages. Often you can’t.

But conceptually using Patapage on your blog is not the right approach: the aim of Patapage is for example making it easier to connect and integrate your blog and your site contents, and also discussions related to the content published on your blog and what is shown on the site. Several Patapage tools, like RSS, Twitter, Delicious, Google custom search integrations (fully explained in the following) ease the integrations of blogs and sites.

So the idea is: use Patapage on your site to connect it with your “social” image – your blog included.

2.9.1 Putting together quickly and simply “sparse” sources from blogs

You have several sparse contents on the web “talking” about your site: how to quickly and simply link them (maybe with a short comment) from your site? Well, a “PataWiki” button on your page is the ideal solution. You insert your first commented link, and when you insert the second, what was a single content automatically becomes a list: all is done for you by Patapage.

2.10 More examples

Many more examples are possible: embedding videos, music, lists, screenshots, Balsamiq mockup drafts, charts, custom Google searches, and more. In the demo site you can find detailed examples of each functionality.

A nice blog post introducing some Patapage usages:

9 ways to improve your site but you don’t know how to

http://pupunzi.open-lab.com/2010/05/13/9ways

Recap

We’ve seen a few websites enhanced using Patapage. In the following we’ll learn how it’s been done.

3. Patapage user guide

Here we see how to use Patapage in building and enhancing sites. We begin with a few general advices, and then a tutorial for the first button creation. Then we proceed seeing each functionality in detail.

You will be generating and pasting some “code” (scripts) in your pages: don’t be scared, you don’t need to be a JavaScript expert or even familiar with it to use Patapage proficiently, as we hope this guide will show.

Of course if you are proficient with JavaScript, you may find a wider spectrum of Patapage applications. See 4 Advanced usage.

3.1 Starting

3.1.1 What you need to start

You need… a site you can edit.

The basic site on which you intend to use Patapage can be built with any technology whose final output is HTML and JavaScript readable by the current browsers. The simplest solution for building the basic site. A simple HTML editor and an FTP client is all you need:

Figure 7 Dreamweaver as FTP client.

Figure 8 WS FTP: the simplest FTP client

Of course most designers use (at least) Adobe’s (former Macromedia’s) Dreamweaver: http://www.adobe.com/products/dreamweaver

To the basic HTML tools you should add a Patapage account, which you can get at Patapage site by selecting “sign up”: http://patapage.com

If you want to use say your Gmail account to sign up, you can use the integrated Open Id procedure – click on OpenId.

Summing up, once you

can create HTML,
have a Patapage account where to generate the scripts,
you can FTP the resulting pages and check them online

you are fine.

A good idea to test the resulting site you are getting is to have two browser instances open, of a different type in order to be sure they won’t share the “session”, i.e. if you login on one, you won’t result as logged on the other.

For example, you log in Patapage in a Firefox instance and check the resulting pages on a Chrome or Safari instance. The site administrator normally sees several active options and actions which the anonymous user doesn’t.

Content for the site administrator.

Same content for an anonymous user. Notice that in this case we chose to show contextually also the login button.

3.1.2 What you don’t need to start

You don’t need a dedicated server with applications. You don’t need to build by hand all the functions provided by Patapage, hence you can focus on your specific problems.

3.2 An example in detail: adding a docked feedback button to your home page

Now that you have your site editor ready, you can try adding something to the site. Let’s say you want to add a docked button labeled “feedback”, which will let visitors of the site to leave you feedback – “comments”.

And let’s just say that we want the button to “stay on top” of the home page.

So this is our goal for this section: a docked feedback button for the home page.

Log in to Patapage, and notice that in the upper part of the screen it is displayed for which site you are adding features – as you may use the same Patapage account for multiple sites.

The feature that we need is under “comments”, so click there, you will either find yourself directly in the button creator screen (if it is the first time you create a comment, and hence there are no comments saved yet), or you’ll have to click the “add new button”.

In all cases this is the button / link creator screen:

This is the entry point to all your “button” generation.

The idea of “generating a button” in Patapage is partly misleading, as it is only one of the possible examples of Patapage usage. We’ll get in more detail after the first examples.

Let’s stop for a moment on this form:

Here you specify what will be the label shown of the button or link. As this is necessary, only once you filled this the following step of the path gets enabled.

These are some steps that guide you to generating the button / link and to set what will happen on a click on it.

In this side pane you get an interactive “preview” of what the generated button will look like and what will happen on the page when clicking on it or even directly on loading the web page.

Let’s get back to creating our first button.

Once the label is written, your first choice is enabled. The choice is: the content which is “activated” when clicking on the button / link (or at page load) is shown in a docked window or in place on the page where you published the button?

If you make the choice “The content is windowed”, you’ll get the preview:

Try alternating the two choices; you will see the preview pane change:

Suppose we make the “The content is windowed” choice (and yes, for the moment we ignore the “more” button). Then notice that the second step is now enabled:

As our button is for the home page only, we pick the “content is unique to each page” choice.

A detailed explanation of each step options is in the next section. Now we focus on generating the first “button”.

We then choose “Click on a button to show the content”, step 4 is disabled as useless in this case, and we get to step 5 – we’ve finished:

And now the “magic” button “generate code” has appeared at the bottom of the page:

this is what we needed to have the script to publish. In this case the script both draws the docked button and enables on it the opening of a docked window of “contributable comments”- which is the goal we had at the start of the section.

What is a “script”? For us here a script is some JavaScript code that can be pasted on a website page.

Let’s temporarily ignore all the information about button properties and the rest which is presented above – just notice that in the preview pane you can now “play” with a preview of your button.

3.2.1 Preview the button

Patapage provides a test page where you can test your button before publishing them on your site. If you click on “Test this button / link” you will open the test page source:

Your test will be in 3 steps:

The code generated by the options you’ve just chosen is presented on the left: select it and copy it
Now you can paste the code in the HTML area on the right; paste the code in a “legal” part, that is, non inside a tag definition or scope. Bad examples:

<title>Patapage test page [NOT HERE]</title [NOT HERE] >

Good examples:

<br class="clearfloat"/> [HERE IT’S OK]

</body>

3. Click on “preview”:

3.2.2 Generating the code

After you made your choices, and eventually back from the test page, click on “Generate code”:

This is what you’ll get: some JavaScript to paste. Now open your web page editor, paste the script obtained in the page, say in the bottom of the HTML, like before the closed body tag, </body>.

Be careful not to “forget” the end of the script, the closing tag </script>.

Publishing the page on your web server, you should obtain something like:

The little script you pasted has drawn a docked button “on top” of the underlying page. If any visitor of the page clicks on it, she will get this window opening:

If there are no comments yes, she will get just the “Post A Comment” part below:

The layout of both the docked button and the opened window are deeply customizable – next section.

So this is done: we have our feedback button. Great!

Take care that the “domain” – the website root address – where you are publishing the page should be the same which you “declared” when you enrolled in Patapage. If this is not the case, you can go to “settings” and add a domain.

If on clicking the button you got the message “your site does not conform …” – it means that the domain under which you registered in Patapage and the one under which you are publishing are not the same. By default on a user and site registration, both the “root” domain and its “www” version are registered in Patapage – for example http://example.com and http://www.example.com. But if you are using a different sub domain for publishing, like http://test.example.com this should be recorded as alias in the Patapage site settings.

3.3 Customizing buttons, links, windows

In this section we repeat what we did in the previous one, with slight variations (in order not to be boring) and examining deeper the possibilities of each step.

This time our goal is to put a link on an image of a menu list which will open a “contributed contents” docked window.

Just like the “Discography” link does it here:

http://patapage.com/demo/wiki.jsp

So let’s get in Patapage and select the PataWiki type. Again we have the “make your choice” field asking for a label.

You may be wondering: our goal is to set the functionality on the click of an image which we already created – what is then this label about? Don’t worry – you can write anything there, it won’t be relevant for our case.

Again we want to get a “windowed” contents, but this time we select the “more” button. A rich (scary?) set of options now opens up:

All these options let you customize the appearance of the opened window (or in place contents, if you are using that). This way you can have a layout consistent with your site and also between several usages of Patapage services. Most of these options are available across the button types.

In this first step, Step 1, we define the appearance of the window displaying the content. Let’s see the properties in detail.

3.3.1 Step 1: Header properties

Hide header and footer: Every Patapage “content” be it a set of discussion threads, a wiki like contents, a search result, appears in a “window”, in a graphical context. This context can have a specific header and footer. This is how the content is structured and presented to an anonymous user visiting your site (not the site admin):

Figure 9 Schema of a Patapage docked window

For example, you can see all the sections in “action” on the demo site “Discography” contents:

WARNING: This will look horrible, because we want to show clearly the different sections. When you use on your sites, you can do better…

In this case the contents are not editable to anonymous users, so the edit/add buttons are not there. But notice that there is the login button, so that a site administrator could work on it “in place”.

If you are logged in Patapage and you click the button navigating on your site from the same browser instance, you may see something different from what other users see. This because you being logged and being the site administrator, Patapage “recognizes” you and enables more links / functionalities.

In case the site administrator logs in, the page is more interactive:

We see that the window’s header, footer and contents are all editable in place, without the need of getting in the backoffice part (which we’ll see later).

Of course on our demo, in order to make it nicer, we can disable all this (regenerating the button), getting again the demo below:

3.3.2 Step 1: Screen properties

These are all properties of the window opened by our button or link. They should be self-explanatory.

3.3.3 Step 2: The scope of the contents shown

The choice we are making in this step concerns the “scope” of the contents presented in your window.

What “The content is unique to each page” means

This means that if for example you create a button or link “feedback” (or “help”) that is in some kind of site footer, and shows up on every page of your site, its content is customizable in a different way for each page.

This is an important and powerful feature: here Patapage is not just a link to an external, “unstructured”, feedback service, but is a tool allowing refinements valid and different for each page of your site.

The distinction between contents is given by being the pages called with different URLs.

The “remove page parameters” allows you to control what defines the uniqueness of a page: is the page
http://example.com/blue.htm
the same page as
http://example.com/blue.htm?redir=true
If for you it is so, you should enable this checkbox.

Until you will have the need of multiple buttons pointing to the same contents, you can safely ignore this step and simply pick “The content is unique to each page”.

What “The content is transversal to site” means

Let me make an example: suppose you have a site selling shoes. You have a description of a specific shoe, let’s say called “Alligator blue” and you carefully edited it in time. Now you decide that among your shoes, you want this week to have the description of the “Alligator blue” shoe on the home page. You want the same contents, the description of the “Alligator blue” to appear on the home page and in the shoe specific page: in this case we would say that a particular content, the “Alligator blue” description, has as scope two pages (at least).

In order to connect a window and its content, Patapage puts in the button creation script a field called "content key”. We ask the question “The content is unique to each page” or not exactly because we want to give the designer the opportunity to specify a content key, so that several buttons, links and contents in place could share the same “content key”, and hence point to the same contents.

For example, our “Alligator blue” description could have “alligatorBlue” as content key, so you could see it both in the home page and in some other section, and any update done to the description of “Alligator blue” would immediately be seen wherever it is referred to.

The distinction between a content and a window tends to get blurry, because most of the time the window and its content share the same destiny. You may even use Patapage proficiently simply without being aware of this distinction.

3.3.4 Step 3: when to show the contents

This is a simple step: you just have to decide whether to present the window when the user clicks on some button(s) or link(s) on the page, or showing it directly on the page load.

If you chose the latter, “The content is shown just when the page is loaded”, you will enable step 4, which is unnecessary and hence disabled in the former case.

3.3.5 Step 4: opening the window with a button

As you’ve chosen to open the contents on load of the page in step 3, here you decide whether to show on the page also a “controlling” button, so that when the window gets closed, you will be able to reopen it without reloading the entire page.

3.3.6 Step 5: button properties and more

This is the last step: you can choose which button to generate, whether a docked button provided by Patapage or a link embeddable in your pages.

If you pick the first choice, the button will be generated by Patapage, not by your design, so you can customize some of its properties through this web interface, like background and text color, text vertical orientation.

Actually the second choice, “It’s a link”, allows you to enable the Patapage function you are generating, in this case the docked window, on any DOM element, be it a simple textual link, an image, even your own home made… docked button! It is sufficient that you element has among its classes the “externalUniqueSelector” script variable value – more on this in the next chapter.

The “It’s a link” option

In this case the script generated will be acting on an element of the page built by you. Actually at the top of the script Patapage provides an example usage, which should be either used or replaced by your own (not both left there when pasted and used in some of your code though).

For example, this is a sample top part of the generated script:

As you can see at the top of the pasted code there’s an <a> tag that you can place wherever you need on your page; for example you can move it to your page menu or inside your text, you can add special CSS classes or manipulate it via JavaScript. The only important thing is not to remove the class, needed to attach the correct behavior to the click action.

The

<a href="javascript:void(0);" class="__patapage__14">Feedback</a>

part is the example usage. Whichever <a> element or image or whatever has an “onClick” event, if it has among its classes the “__patapage__14” class, it will launch the selected Patapage behavior.

If it looks strange to you the usage of a class as a selector, this is standard practice in today’s JavaScript.

The best way to understand it is… trying it out.

Configuring the community service

In both cases you will have to configure the button or link “security”. By this we mean that all contents served to sites by Patapage are subject to a security check. You may want certain contents to be shown only after moderation, certain to be shown in read-only mode, some to be editable by everyone. You can configure this globally, page by page, or content by content. The simple choice presented below

gives great flexibility:

- Allow unverified: means that users whose identity has not been verified through an e-mail verification process can act on the contents presented in your window

- E-mail confirmation: means that only users that have confirmed an e-mail message can edit the contents presented in your window

- Editor only: only the site administrators (there may be more than one – see the backoffice section) can edit the contents presented in your window

- Activate moderation: in case the choice is “Allow unverified” you can be open to contributions, but by having this option active contributions will be visible only after you will have checked them.

With Patapage regular users of your site - members of your community - can be managed through the backoffice on the contributors page (more on this in the backoffice part).

3.4 In place contents

Most of what we‘ve seen and explained in the previous section is valid also for “in place” contents. What do we mean by “in place” contents? Much of what gets created through Patapage can be used not only in docked windows, but also “inside” your page. You could for example have a news box on your site that can be updated in place using Patapage. The effort? Pasting a script.

An example: go to http://patapage.com/demo/fullSite.jsp

If you click on “Tour”, you’ll get:

The “Tour countries and dates” text and images is a content inserted with Patapage, here it is in the Patapage backoffice:

If you click on “about”, again more contents in place:

Now, how do you generate buttons and links to handle this? It all happens at the very first step of the button / link generation:

Selecting “more” can help you understand how it works:

So the content you are inserting either in place or through the backoffice (see the next section) will be inserted in your page “inside” the element whose id is “About_ppPlaceHolder”.

For example, in the case of the page of the demo above, the button “Tour” refers as placeholder where to insert the contents to “patawikiMain”:

This same placeholder is referred by the “about” link, that is why they “operate” on the same area.

Some layout elements won’t be used in case of in place contents don’t get used, like headers and footers. A schema of the result:

You may be tempted by the idea of building an entire site contents with contents in place: don’t do it. You may end up having performance, indexing and layout problems. In place contents are ideal to supply easily editable and updatable areas of your site, like news.

3.4.1 Customizing contents in place: buttons and layout

Here is an example of comments in place customization:

* COMMENTS IN PLACE CUSTOMIZATION

/*general comment container*/

#pp__screen{

width:500px;

margin:auto;

}

/*button*/

#pp__screen .pp__editLabel{

-moz-border-radius:0 !important;

-webkit-border-radius:0 !important;

background-color:#4f6e71;

color:white;

}

/* Each comment*/

#pp__screen .pp__cmt{

-moz-border-radius:0 !important;

-webkit-border-radius:0 !important;

background-color:#fff8dc;

color:#696969;

}

</style>

This code should be placed just above the place holder div. To be sure all the new styles are applied you could use the "!important" class attribute as in the example. To know which class you have to redefine use any of the developer tools available for your browser and analyze the code J

For example you could use the well known Firebug tool for Firefox.

http://getfirebug.com/

3.5 The backoffice

Up to now we have accessed Patapage “backoffice” only in order to generate buttons. But accessing your Patapage account gives you much more: you can monitor and moderate new contents and contributions, see who has contributed, manage more sites, see statistics, buy and renew the service activation.

3.5.1 Filtering and editing contents

This is a typical backoffice home page:

As a single account can be used to manage several sites, in the upper part you have a “combo” which lists the sites you have activated and lets you pick the one whose contents you want to manage.

If you pick one, immediately the list of contents below will be filtered and updated.

The central list of contents is ordered by most recently updated and filtered by site (if one has been chosen). If you pick a type on the left list, that too will be added as a filtering criteria. If no elements are found satisfying the criteria, you will be presented directly with the “add button” form.

Yet another filtering tool is given by the “Filter by…” combo, which filters contents by “content key” – read next chapter for a detailed explanation. Simply said, it filters all contents that may appear in the same list in a docked window or in place contents.

Each content can be edited, just click on “edit”:

Depending on how you created the button / link, when you are logged on the backoffice you may find a similar editor also directly in place going to the site in the same browser instance. In my case, to the backoffice editor above there corresponds an editor in the site page:

Clicking on edit:

And so you can edit the contents remaining on your site. Now we’ll edit from the backoffice. We search for the contents:

And finally get to the editor:

The editor lets you edit all contents, and also the contributor’s data:

The “publishing date” field lets you set a date which will be used to order contents, and can also be used to schedule a future publishing date. The date will be displayed according to the format set at site level.

The “permalink” is an absolute (i.e. complete) URL at which the content can be found, can be accessed directly.

For each contents its complete revision history is preserved. This is useful but actually essential in case you want to use contents as a kind of wiki: restoring a good, previous version should be very very easy. Don’t confuse “delete” with “restore previous”! “Delete” will delete the contents and its entire history.

And a complete “diff” is provided:

3.5.2 Site settings

Once you focused on a site, you can click on “edit” to view and edit its settings.

Now this is quite a looong page, fortunately you’ll have to go here rarely. It also gives you a lot of control on the site behavior (for the Patapage part).

From this page you can set site domain and aliases, map domains using CNAMEs, set cross-site docked windows headers and footers, share site management with other users, configure anti spam settings, export all the site data (also images), customize the operational button labels (like “edit” or “add new”) and remove the site entirely (careful – non recoverable).

In the rest of this section we’ll look at the details of the operations above.

Basic configuration

Your site is identified by a domain, or by a sub domain. If you have one or more aliases you may set them here. See also section 4.4 Indexing and analytics.

The “suspend notifications” checkbox stops Patapage from sending e-mail notifications to the site owner and editors about new contents created by contributors.

The “mapped subdomain” can be used to get under your domain all the contributed contents, and hence get them locally indexed by search engines. This solves a classical problem of mashups, and of any delegation of contents connected to your sites to some external source.

When a date is shown on your site on say a docked window, it has to be displayed according to a format. The default EEEE, MMM dd yyyy means

“[Day in week in explicit format], [month in explicit format] day [year in four numbers]”

e.g. this will be: Monday, January 11 2010

You can set your own format, e.g. dd MMM yyyy which is [month in explicit format] day [year in four numbers].

This is the standard used:

http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html

Dafaults in layout

By default this section is closed, as often it is not used. You can here set the default window header and footer for all your docked windows.

Collaborators

Here you see the list of the users with which you share the site backoffice maintenance – all of them can edit all contents, set them as approved etc. . You can set some of these users as site “admin”, meaning that they can also edit site settings.

To invite someone, just write their e-mail in the “invite someone” field and select “add”. They will receive an e-mail from Patapage with a confirmation link. You won’t see them among the active users until they’ve confirmed the invitation.

Anti spam

Patapage contains an anti spam engine that can be turned on when receiving some contribution, comment or similar. In order to perform an accurate spam analysis Patapage needs some sample good text which determines the topic's context, where by “good text” it is meant something which is a typical of the text contained in the site.

You either provide such text by pasting it in the text area, or provide some of your site URLs where Patapage can try to download the text (say with a purely Flash site this won’t work).

Data export

Your data is not “imprisoned” in Patapage. You can any time make a complete export of all the contents, comments, and so on, together with all the connected files (images, documents, …). It is a good idea to do this export periodically, as a backup.

Deleting your site

You site can be completely removed from Patapage. It is a non reversible action – do it only if you are really sure. If you decide to stop paying your Patapage account, you still don’t need to delete all data from your account – you may change idea in the future.

Customize labels

If you go to the top of the web site form, there is a further tab, “Customize labels”, and if you open it, you will find an editor that lets you customize at site level the labels of all the in place Patapage actions.

3.5.3 User settings

By clicking on “settings” you will access your user settings, which include your sites list, subscriptions, and account management.

For each site you have its e-mail subscription status, and whether the site is “enabled”. When a site is enabled, the calls to Patapage on the button’s clicks and page loads will serve the contents; for the disabled ones, no content will be served.

Here you can set how many elements to show on the home page.

Here you can add a further site which will be enhanced with Patapage.

Buying the service

From your settings you can buy licenses:

See all details below in 3.6 Buying the Patapage service.

Good bye Patapage

This is the case where you are not using Patapage, maybe for a while.

Before unregistering, you must remove all your sites by hand in the site editor, and then the “remove me” button will become clickable. By removing your account you will not be able to login anymore. You can enroll again anytime, starting with new empty sites.

3.6 Buying the Patapage service

Making Patapage be paid by the users is be a way of keeping it ad-free: as one of our ideals is to give as much as an unobtrusive service as possible, channeling ads would result in just the opposite. We also believe that using a commercial service is a higher guarantee for the users.

From your settings you can buy licenses:

Patapage is a commercial service, and has a cost, which depends on whether you want to manage a single site – “basic” account - or several sites – “pro” account. The costs as presented in the pricing page:

BASIC account - 1 site

This lets you manage a single site (plus a single alias). The cost is 9 USD / month (in Euro, 6 EUR / month), if you buy on a month-by-month basis. If you buy a full year of service, the total cost is 89 USD (in Euro, 68 EUR), that is, 7.4 USD / month.

PRO account - unlimited sites

With this account it will be possible to manage an unlimited number of sites and aliases. The cost is 39 USD / month (in Euro, 29 EUR / month), if you buy on a month-by-month basis. If you buy a full year of service, the total cost is 390 USD (in Euro, 299 EUR), that is, 32.5 USD / month.

The cost of a PRO is really convenient, if you think that it is all is needed by a web agency to use Patapage on several sites. It is a way to have the tool always available, for the most diverse applications.

This price of an account covers up to 5000 contributions and revisions per account per month; in the unlikely case you get more than 5000 contributions per month, we congratulate you, and we will contact you for evaluating the bandwidth and resources used and revise the price. In our experience the 5000 contributions limit would be reached only by sites with a huge following, like a major online national newspaper site.

3.7 More on button types

In our examples we haven’t seen yet some of the buttons available and some of functionality the specific to the buttons.

3.7.1 PataWiki

A “PataWiki” button / link actually is a way to add any kind of web contents (html) to your pages and docked windows. This functionality is so general that it is hard to find a name for it - that’s why we created a new term, “PataWiki”.

Adding a wiki-like button (“PataWiki”), actually adds to your web page a layer of dynamically updatable content, by both the site maintainer and site visitors (if that is what is wanted). This could be a “help” page, contributed contents, a “more in depth” presentation, a “buy now” page (we’ve seen it online used this way already), a way to publish news… .

Any single content can become (it the site owner wants to) a list of contents. Think of a blog home page: you can have a single post, and change / comment that, or have a list of blog posts, and edit / comments for each of them. The list of contents introduces a similar functionality.

PataWikis (or simply contents) have one specific field: “Hide publishing date” that when selected will stop the publishing date to be shown in the contents.

3.7.2 Comments

An additional feature that appears at the last step when you are creating a comment button / link is how the list of comments should be structured, whether flat or as a tree, and whether to show the Gravatar (http://gravatar.com) image for each participant.

3.7.3 Image gallery

You can use Patapage to embed / add a photo gallery on your site in minutes. Currently you need to have the gallery on Flickr (http://www.flickr.com), which is a well known service for managing images on the web.

Once you get beyond the button / link choice, you will have the Flickr configuration panel open.

Set Id: this is the ID of the Flickr Set you want to show in the gallery; keep in mind that the ID is not the entire URL of the set but just the last long number

For example:

http://www.flickr.com/photos/pupunzi/sets/ 72157600884372818

The ID is “72157600884372818”.

Api user: this is your Flickr account user name.

Api key: this is your personal Flickr API key. To use this component you need a personal Flickr API key; to obtain your key just browse:

http://www.flickr.com/services/apps/create/apply

Patapage uses the Flickr API but is not endorsed or certified by Flickr. http://www.flickr.com/services/api/tos/

3.7.4 Forms

The form functionality really adds a lot to any site that does not want to fight with server side configurations and problems. The contact form is a simple and ready form:

“target e-mail” is the e-mail to which the contact form contents will be sent. You will also see those from the backoffice list.

If you pick “build your own” as form type, you will have at your disposal a set of field tyopes which you can combine to build the most diverse forms:

So we can start adding fields to the form:

And here is the result on the test page:

3.7.5 Rate pages and contents

The rate function is so simple that it just needs a label. You’ll get all the statistics in the backoffice:

3.7.6 Retweet

The retweet function too is very simple:

“Default twitter comment” is the text that will by default fill the tweet input field.

“Prefix” is the Twitter user account to which the re-tweets will refer.

3.7.7 Twitter search / filter

Here you set the text that will be searched in Twitter. The number of results shown is given by the “List size”.

3.7.8 Windows on other sites

This is a simple but very powerful functionality.

Patapage will load in the docked window the URL you inserted. We have seen a lot of usages of this function, like adding a site that handles an e-shop (cart etc.) in a window so that the user is “kept” on your site anyway.

3.7.9 Google search

This button makes the Google custom search engine run over your site pages. You are getting the most powerful search functions on your site for free.

If you use it as simple link, Patapage will supply an example search input whose target will be a docked window with the search result – ready for your site:

Google search for your site lets you “Customize the look and feel of the results to match your site”. See http://www.google.com/cse for more information about Google custom search.

Search only within my site: this restricts the scope to your site only.

Default filter: the filter that will be used when opening the search window.

This component uses the Google Search API but is not endorsed or certified by Google. http://code.google.com/apis/ajaxsearch/

3.7.10 PataPic screenshotter

PataPic is a functionality that lets you take screenshots of web sites and have them available as an online URL, a bit like the TwitPic service (http://twitpic.com) for Twitter; PataPic also lets you download a Balsamiq Mockups (http://www.balsamiq.com/products/mockups) file which contains a “sketched” version of the site image. You can use this for example to get feedback on drafts of new pages.

An example usage: One Look is Worth A Thousand Words. Say the site is our example one, Liz’:

and you are its designer and you’ve built a draft of the new version of it: now you want to show it around, giving the opportunity of making suggestions for improvements. Just add the PataPic button to such page(s), and when the visitors / contributors will click the button they will get the image generator page:

Proceeding they will get the URL to the screenshot:

Now they will have a public web link to the image (which may even be shortened), and if they have Balsamiq Mockups installed, visitors can download and open the bmml file (the format supported by Mockups), obtaining in this case:

Ta-da: Your site in Mockups. Notice the cool “sketch it” effect: this way the user added notes are more readable, and it is immediately clear that your proposal isn’t the original site. Once they have completed their annotations, say obtaining this:

they can contribute the file or its screenshot back on the page using PataPic upload, getting:

You can see all this on a sample page here:

http://patapage.com/demo/patapic.jsp

or even better you can enroll in Patapage and try it on your site or on a test page.

We thank the Balsamiq guys for feedback. Get the Balsamiq Mockups application from this site: (produced by Balsamiq Studios):

http://www.balsamiq.com/products/mockups

One Look is Worth A Thousand Words: http://en.wikipedia.org/wiki/A_picture_is_worth_a_thousand_words

3.7.11 RSS

“You can use RSS channels to allow customers to keep up on industry specific news, check weather, look for jobs, view upcoming concerts or university lectures, monitor specific websites, and much more.”

From Publish and Syndicate Your News to the Web

In Patapage you can use any RSS feed to display contents on your pages. An example is online here:

http://patapage.com/demo/rss.jsp

where you see two buttons which open Patapage’s blog RSS, the first one displaying abstracts, the second one displaying full contents (see the screenshot below).

The first example that comes to mind is to use your blog posts as news for your site. Or to enrich a page on a specific topic with one or more feeds of blogs or sites specialized on that topic.

Or say if you want to read from a Twitter stream, fortunately on any Twitter stream the RSS is always available.

So for example in the unlikely case you want to feed a page with Pietro’s Twitter stream, you have already three choices in Patapage: use the Twitter button, use it as RSS stream, or use the window component to load the Twitter page directly.

Almost all mature web sites / services expose their “products” in form of RSS feeds; in the example page we’ve put also

- the Rolling Stone recent reviews,

- the New York Times news from the home page,

- Amazon’s best sellers in books.

Of course Patapage also works “the other way round”, as supplier of RSS news: e.g. the list of comments for a page can be read in RSS form – if you enable RSS when generating the button.

Here you see how Patapage “empowers” a web site, with almost no development and maintenance effort for the users :-)

These are the RSS specific properties:

Which should be self-explanatory.

3.7.12 Data chart

The chart functionality let’s you define data series and add them on any page of your site, in different styles. A demo is here:

http://patapage.com/demo/chart.jsp

This is how a chart can appear to a visitor.

If you log in and have the rights, you will be able to insert and edit chart data. Picking “edit data” you get and editable list of data, editable in-place in the browser:

and you can add series on the fly, change data etc. Picking “edit configuration” a host of options for your graph layout appear:

and you can play and get your desired graph.

Patapage chart bars

Notice that the chart preview changes on the fly while you do your tests.

Also Patapage will keep a (deletable) history of changes you (or others) did on the chart and data, so that it is possible to recover a previous version and see the history of changes – as with all contents. In fact, you may even ask site visitors to contribute data.

In this blog post, JavaScript charting tools: an overview, Roberto Bicchierai (one of Patapage developers) talks about the jqPlot library we used and why it was selected.

3.7.13 Delicious bookmarks

Patapage can generate a “delicious” filtering window, as shown in this demo page:

http://patapage.com/demo/delicious.jsp

Delicious (http://delicious.com) is a very well-known and very simple online service for bookmark sharing, which can be used for all sorts of bookmarking. An example usage is in this blog post, Tracking your Company’s Mentions with Del.icio.us: http://balsamiq.com/blog/2009/12/20/delicious/

Any of the delicious generated feeds, as documented on Delicious site (http://delicious.com/help/feeds), can be used to create or expand an existing page with Patapage. This way several people can share links relative to contents on your pages, contributing new sources of information.

In the “filter” field you should set a tag which is related to the contents of your page. You can also combine tags with the “+” notation. For example, setting as value “tag/patapage+bugsvoice” will get you here:

http://feeds.delicious.com/v2/rss/tag/patapage+bugsvoice

This is the content which will be grabbed by the Patapage window on your site (and showed in a friendlier graphical style).

3.7.14 Audio player

Audio player lets you add a music player on your site:

It handles both single files and playlists. The button / link has no special parameters, as all configuration is done in place, once you are logged in.

This way you can publish your podcasts, music files, any mp3 file in the context of your site. Easy to set and to maintain, as all Patapage J

A demo page is here: http://patapage.com/demo/mplayer.jsp

Thanks to Happyworm and their jPlayer: http://www.happyworm.com/jquery/jplayer/ that has made this integration much easier than it could have been.

3.7.15 Video

You can embed videos in your pages and windows.

Apart from the video width property, all the compilation editing is done “in place” on the site:

Recap

This chapter pretty much covers all the main Patapage features. You can end your reading here, and use Patapage happily for quite a while.

4. Advanced usage

In this chapter we will examine the details of the scripts generated by Patapage and technical aspects of the “environment” where they are used. We’ll also examine the relationship between the contents internal to Patapage and site indexing.

4.1 Examining the script you are pasting

This is a typical script generated in Patapage:

<!— EXAMPLE USAGE BEGIN begin rendered link

Place this part wherever you want in your page code. -->

<a href="javascript:void(0);" class="__patapage__15">Feedback</a>

<!— end rendered link EXAMPLE USAGE END -->

/* patapage.com button: PataWiki */

if (typeof document.__pataButtons == 'undefined') {

document.__pataButtons= new Array();

document.write(unescape("%3Cscript src='http://patapage.net/pp/pp.js?16439' type='text/javascript'%3E%3C/script%3E"));

};

document.__pataButtons.push( {

/* NON CUSTOMIZABLE PART - DO NOT MODIFY - BEGIN */

/* externalUniqueSelector defines how to refer to this from your page html/javascript

You can use '__patapage__15' as a class selector */

externalUniqueSelector: "__patapage__15",

type:"CNT",

key:'yf8f3df0b9805a483642184513d9e3c353585b4da2f57b1e9ddb4f84063922c7fa2ae1b148f5d3cd2010577060b3b032fb5c80adf383bd5aa0542460b9b21bccc951ybikr17',

/* NON CUSTOMIZABLE PART - END */

/* 'content key' points to the server side contents */

contentKey: self.location.href + '_Feedback',

/* button */

textual:true,

label: 'Feedback',

/* screen */

openOnLoad:false,

activateRSSChannel:true,

screen_background_color: '#FFFFFF',

screen_text_color: '#000000',

screen_overlay_background:'#000000',

closeLabel:'',

screen_overlay_opacity: '0.7',

screen_position: 'top',

screen_width: '70%',

screen_height: '90%'

});

</script>

Several customizations operations can be done by changing the script by hand – but be careful. Let’s examine each part in turn.

The example part

<!— EXAMPLE USAGE BEGIN begin rendered link

Place this part wherever you want in your page code. -->

<a href="javascript:void(0);" class="__patapage__15">Feedback</a>

<!— end rendered link EXAMPLE USAGE END -->

This part will be missing, if you generated the button as a docked one. This part will likely be moved elsewhere or removed – it is the clickable part of your code that will launch Patapage.

Loading Patapage’s logic

/* patapage.com button: PataWiki */

if (typeof document.__pataButtons == 'undefined') {

document.__pataButtons= new Array();

document.write(unescape("%3Cscript src='http://patapage.net/pp/pp.js?16439' type='text/javascript'%3E%3C/script%3E"));

};

This part simply loads the Patapage script. Leave it as it is.

The function identifier

/* NON CUSTOMIZABLE PART - DO NOT MODIFY - BEGIN */

/* externalUniqueSelector defines to refer to this from your page html/javascript

You can use '__patapage__15' as a class selector */

externalUniqueSelector: "__patapage__15",

type:"CNT",

key:'yf8f3df0b9805a483642184513d9e3c353585b4da2f57b1e9ddb4f84063922c7fa2ae1b148f5d3cd2010577060b3b032fb5c80adf383bd5aa0542460b9b21bccc951ybikr17',

/* NON CUSTOMIZABLE PART - END */

This part of the script should not be modified – the script will stop working otherwise.

By “external unique selector” we mean the value that allows parts of the page where the script is pasted to refer to it. "__patapage__15" identifies the function triggered by this script. You should refer to it as a class selector, as done in this example:

<a href="javascript:void(0);" class="__patapage__15">Feedback</a>

Referring to the contents

/* 'content key' points to the server side contents */

contentKey: self.location.href + '_Feedback',

The “content key” value is the key used by the functionality triggered by this script in order to find a Patapage contents. For example, if this is a button that opens a docked window, which content should be shown in the window? And one content or a list? For the given Patapage site account, the contents will be filtered by the content key value, and the matching content(s) will be displayed.

You always see the “content key” for each content from the backoffice editor. Checking this is also a way to make several buttons and links point to the same contents.

In the case of the example, the content key value is “semi-automated” using JavaScript: the content referred to by the function (in our example, the content key of the contents of the window) has as key the URL of the page plus “_Feedback” – the label. So if the button is pasted in a page called http://example.com/mypage.htm, the content key of this button will be:

“http://example.com/mypage.htm_Feedback”

Notice that the entire URL is considered, parameters included, so the page:

http://example.com/mypage.aspx?item=1

and the page

http://example.com/mypage.aspx?item=2

will refer to different contents.

If this is not what is wanted, when generating the button / link you can just enable the checkbox “remove page parameters” and content key will be determined this way:

contentKey: location.pathname +'_Feedback',

So only the URL path and not the parameters will be considered.

Finally, the content key can be completely set by hand, and by default its value will be the label. You can actually give it any value whatsoever, e.g.

contentKey: ‘Whatever’,

You may change this value any time, but you may end up referring to a non existing content.

The in-place hook

In case you are generating a content in place, there will be this important additional field

// the DOM element ID where Patapage will print out the content

placeHolderID: 'llklk_ppPlaceHolder',

This is the id of the “location” in your web page where the contents from Patapage will be inserted.

Display values

All the other values can be modified and change the appearance of the opened windows / contents. All the possible values are explained in detail in section 4.3
The complete commented list of script variables below.

/* button */

textual:true,

label: 'Feedback',

/* screen */

openOnLoad:false,

activateRSSChannel:true,

screen_background_color: '#FFFFFF',

screen_text_color: '#000000',

screen_overlay_background:'#000000',

closeLabel:'',

screen_overlay_opacity: '0.7',

screen_position: 'top',

screen_width: '70%',

screen_height: '90%'

If you have the variable “placeHolderID” set in your script, as the contents then will be in place, all the screen properties will be ignored.

4.2 Encodings

When selecting the script, there is a warning: “This editor is encoded in UTF-8. Consider your encoding when pasting.” Every web page, actually every textual file, is “encoded” according to some encoding standard. As long as you are using as your button label characters that in the basic ASCII set, e.g. the basic 26 letters with no accents, you will never notice a problem. As soon as you create a button like “Pizza Napulè”, you may get surprises when you publish the button.

It’s probably a good idea to encode your web pages in UTF-8, so that they will support practically any kind of character. You do this by having in the page head

This way you’ll also have perfect compatibility with the scripts from Patapage.

If you don’t know what encoding is, read this old but still valid introduction to the encoding universe: The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses! )http://www.joelonsoftware.com/articles/Unicode.html

4.3 The complete commented list of script variables

Variable		Group	Default value (or value if not set)		Possible values	Meaning
*Basic*
externalUniqueSelector			Patapage generates a value that is unique.		Anything as long as it is unique to the page where the button is embedded.	It is the value that allows parts of the page where the script is pasted to refer to it For early beta adopters, this was called “id”.
type			Does not apply		A fixed set of three letters codes.	A three letter code for the type. It’s of no use for you J.
key			Patapage generates it.			It’s a key that validates the calls your page makes to Patapage. Just don’t touch it J.
contentKey			Patapage generates it based on the label.		Anything.	The “content key” value is the key used by the functionality triggered by this script in order to find a Patapage contents. See above for a conceptual explanation. For early beta adopters, this was called “pageId”.
placeHolderID
callbackUrl						This is not yet implemented.
*Button*
textual		docked button	false		true, false	Whether the script is pointed to by an existing link (value true) or should create a docked button (value false).
label		docked button	Does not apply (always set by the user)		(Any text)	The label shown on the docked button. It is ignored if textual is true.
background_color		docked button	Does not apply (always set by the user)		All HTML colors.	The background color of the docked button.
text_color		docked button	Does not apply (always set by the user)		All HTML colors.	The color of the text of the docked button.
text_valign		docked button	updown		downup, updown	The vertical direction of the text of the docked button.
hidden
*Screen*
closeLabel		docked window	It is empty.		Any text.	When it is not empty, the text is shown in place of the “X” close image, and clicking it makes the docked window close.
openOnLoad		docked window, in place contents	false		true, false	Case of a docked window: if true the window will be opened directly when the underlying page is loaded. Case of in place contents: whether the in place contents will be loaded directly when the underlying page is loaded. Be careful of not having two scripts on the page with this value true, as only the first will be opened.
hideHeaderFooter		docked window	false		true, false	Whether to hide the window (and site) header and footer on this window.
hideMenu		docked window	false		true, false	Whether to hide the login button on the top of this window.
activateRSSChannel		docked window, in place contents	false		true, false	This means that when true, the RSS channel for the content referred by the function is added to the underlying page. This works both for docked windows and in place contents.
screen_background_color		docked window	#FFFFFF		All HTML colors.	It’s the color of your face when you look at Patapage. No, ok, it’s… the background color of the opened docked window.
screen_text_color		docked window	#000000		All HTML colors.	It’s the color of the text of the opened docked window.
screen_overlay_background		docked window	#000000		All HTML colors, plus ‘transparent’	A background color for the screen which is "under” the docked window when it is open.
screen_overlay_image		docked window	Does not apply.		An http URL to an image.	A background image of the screen which is "under" the docked window when it is open.
screen_overlay_opacity		docked window	0.7		Between 0 and 1.	The opacity of the screen which is "under" the docked window when it is open.
screen_position		docked window	top		top, right, bottom, left, center	The position of the docked window.
screen_width		docked window	0.7		Between 0 and 1.	The width of the docked window, in % w.r.t. the entire page, or absolute in pixels.
screen_height		docked window	0.7		Between 0 and 1.	The height of the docked window, in % w.r.t. the entire page, or absolute in pixels.
*Contents*
hidePublishingDate		docked window, in place contents	false		true, false	Whether to hide or not the publishing date when displaying the contents.
*Comments*
structure		docked window, in place contents	flat		flat, asTree	Whether the discussion thread has to be flat or nested. Replies will be appended to the end or set in place to the question to which they answer respectively.
gravatar		docked window, in place contents	false		true, false	Whether to show the Gravatar image associated to the e-mail of the contributor on the comment list. For information about Gravatar see here: http://gravatar.com/
*Twitter search*
twt_search		docked window, in place contents	Does not apply (always set by the user).		Any text.	The text to be searched in Twitter. “#” prefixed values are accepted.
twt_size		docked window, in place contents	10		Any integer number.	The number of results to show from search.
*Retweet*
color		retweet widget	#529ABD		All HTML colors.	Color of the retweet widget.
prefix		retweet widget	Empty.		Any text.	Prefix to be used in the re-tweet.
*Image gallery*
provider		docked window	Flickr		Currently only Flickr.	The online image service provider.
setId		docked window	Does not apply (always set by the user).		The service photo set Id.	This is service photo set Id. In the case of Flickr, the Id is not the entire URL of the set but just the last long number. For example: http://www.flickr.com/photos/pupunzi/sets/ 72157600884372818 The ID is “72157600884372818”.
*Form*
form_type		docked window	contact		Currently only ‘contact’.	The type of form which should be opened.
*Window*
Iframe_url		docked window	Does not apply (always set by the user).		All public URLs that answer with a web page.	The URL to be included in the docked window.
*Google search*
googleFilter		docked window	Does not apply (always set by the user).		Any text. Google search syntax can be used.	The text for the Google search that will be done in your custom Google search settings.
site		docked window	Empty.		The domain to which the search has to be restricted.	When set it narrows searches within the site on which you are running Patapage.
*RSS reader*
rssUrl		docked window, in place contents	Does not apply (always set by the user).		Any public URL where an RSS feed can be found.	The public URL where the RSS feed will be downloaded.
totalFeeds		docked window, in place contents	10		Any integer number.	The number of results to show from search.
shortContent		docked window, in place contents	false		true, false	Whether to “show abstract of contents”.
*Delicious search*
filter	docked window, in place contents			Does not apply (always set by the user).	The tag to be searched in Delicious.		The value that will be appended to http://feeds.delicious.com/v2/rss/ (likely “tag/mysearch”) to feed the search results. See also: http://delicious.com/help/feeds
totalFeeds	docked window, in place contents			10	Any integer number.		The number of results to show from search.
shortContent	docked window, in place contents			false	true, false		Whether to “show abstract of contents”.
*Video*
videoWidth	docked window			400px.	Any width in pixels.		The width of the videos window.

4.4 Indexing and analytics

Does the “social” content of your static site get indexed under your domain? Normally, no. With Patapage you can get that too.

A common problem of all Ajax loaded contents (like that from Patapage) is search engine indexing of it. In Patapage 1.0 there is a partial solution of the problem; more will be done in a forthcoming update.

The partial solution given is that all contents provided through Patapage are available at a public URL, which you find in the settings part of your site. If you go at such URL, all the contents are displayed, and you can link to that from your site.

The complete solution will be provided by giving CNAME support: this is in fact how the problem is solved normally in relation to blogs and support sites.

An example:

Our product Teamwork is at the domain http://www.twproject.com. Its blog is at http://blog.twproject.com, served by WordPress (http://wordpress.org). The blog is actually on WordPress servers, but all the contents of the blog are indexed by Google under the “twproject.com” domain, which is exactly what we wanted.

If your site is

http://example.com

you could make all Patapage contributions be indexed under a subdomain

http://social.example.com

This should be mapped as CNAME for something of the sort:

http://patapage.com/site/134

this is the URL that can be found under your site settings.

Recap

We’ve seen in detail the scripts generated by Patapage. Now you should be able to control completely its behavior.

5. From here

If you haven’t done it yet, the first thing you should do now is enrolling at Patapage site:

http://patapage.com

and try it out. Before changing some visible page of your site, you could create a non linked page test.htm in the domain for which you registered on Patapage and try pasting Patapage’ scripts there.

Patapage is developed and supported by a small but highly motivated team; you can meet us online and follow our activity and ideas through our blogs and tweets. See the complete staff here:

http://www.open-lab.com/staff.html

Support:

Q&A: http://answers.patapage.com

Submit/vote feature requests: http://patapage.uservoice.com

Follow developments:
blog http://blog.patapage.com/
twitter stream http://twitter.com/#search?q=%23patapage

Direct contact:

E-mail: info@patapage.com
Fax: +39 055 582451
Phone: +39 055 5522779
Time zone: 'Central European Time'
(6 hours ahead of New York)

Quoted brands: All brand and product names appearing on this site may be the trademarks or service marks of their respective owners.

Company’s HQ:

Open Lab
Via Venezia 18b
50121 Florence – Italy
http://www.open-lab.com

Other products: BugsVoice "Turn bugs into opportunities" http://bugsvoice.com/ - Teamwork "Shared work is half done" http://www.twproject.com/ – Licorize “beyond sharing bookmarks” [in alpha stage].

6. It was a sunny day in Florence…

It was a sunny day in Florence, I was walking to meet Liz in the piazza, I didn’t expect her for today. I had left her in Stockholm three days before. There she was, at a small table outside, with aperitivo and iPhone under the shade of her straw summer hat.

I couldn’t resist, after a too brief smile exchange, asking: “You left the web site unfinished?” “No, its done.” “What you mean, done?” “Done. Just done” “But… it looks good?” “Looks just like you saw it, nothing’s changed.”

I had left her at work on the site, with her nice layout done, and a long list of request and services to be put up. I remember contact forms, page relative contextual help, content rating, RSS, feedback, retweeting, iPhone compatible version, a long wish list. In short, they wanted a product site with all the features of a social aggregator. Liz designed the layout and then generated the HTML in Dreamweaver in a day; then I “helped” Liz setting up a local test server for the dynamic part, installing a CMS open source software, and the nightmare of trying to fit her layout started. Actually, she did all the technical work, I just contributed in watching, listening, not understanding, and making coffee, which she was forced to admit was good.

Not only the layout didn’t fit, the available services were ugly and half were missing; it was like the CMS had been done in the 90’s, and the sites were forced to look and behave in that way. Such a small, thin and delicate girl was swearing heavily. I tried to get into the background.

Soon I left for my holyday in Italy, while she was considering programming all the features by herself, starting with basic PHP calls. She estimated a couple of month’s work.

Liz: “And then, while I was searching for a jQuery component” (don’t ask me what that is) “I stumbled upon the pata-something site, with a fatty hero logo, where they showed a list of ‘buttons’, actually online services, which more or less covered our requirements. So I got back to the basic static site, and in 10 minutes I was done.” I looked skeptical. She started talking slower, it was always like that when she tried to explain me technical stuff. “It is like pasting a YouTube video, you just select the layout, and then embed the script” “Hmm.. but the video is fixed, what we needed is changing contents” She looked amazed at my making a meaningful observation. “Yeah, exactly, like you know a comment button, that enables collecting the comments, and you administrator can access them in a backoffice and moderate them – actually, I’ve done just that from my iPhone. So you know it’s like pasting the Google analytics script, then you inspect data collected. You see, it’s so easy that even you could do it.”Even me; my hard life. “And it all took 10 minutes? Come ‘on.”

“Enrolled in fatty’s site” – each time she said fatty, I felt she was hinting at me – “2 minutes, picked the code, 5 minutes, I opened Dreamweaver, pasted it and FTPed the changes, 2 minutes, saw it online, 1 minute. Yeah, 10 minutes”.

And then it happened. We heard a hiss, looked at the sky, and she said “There! Look! It’s him, the fatty hero!”And there he was, flying above too fast to be sure about what we’ve seen.