Documentation: help.php

help.php - The main help index

YACS is the acronym of 'Yet Another Community System'. Of course, this name is a joke - Remember the old days of yacc on Unix?

What can I do with YACS?

Following patterns should be considered only as examples of what can be achieved with YACS.

Weblogging platform - The powerful templating system of YACS supports various skins,

and let web writers focus on what they have to say. Moreover, each weblogger can have one or more weblogs to post in. Actually any YACS section may become a weblog. Of course, an associate may weblog to any section of one site. Also, one or several webloggers can be given editors right to any section. Note that YACS has been built-in features to ping information between servers, and to let surfers comment and discuss any post. Also, posts are automatically archived by weeks and by months.

Original content publishing - Declare managing editors as associates, ask contributing

editors to register as regular members. Use the subscription mechanisms to handle the list of readers, and that's it. Note that YACS has built-in features to let managing editors review articles submitted by contributing editors.

Knowledge community - Declare experts as associates, and let interested people register

as regular members. Experts will use YACS to structure and to share their knowledge. Each article may be commented by another expert or by any member. Files and links can be attached to any article by any member. Note that YACS has built-in features to encourage people to share with others. For example, each profile lists last contributions of this user.

Passionate members - When several people have a common category of interest, they can decide

to setup a YACS server to support their passion, and become associates of this community. Other interested people can register as regular member or as simple e-mail subscribers. Note that YACS has been built-in features to share information between servers, enabling one community to be extended over time.

Web masters that are discovering the yacs environment may use following guidelines to reduce the learning curve. We have assumed that you have a quite strong background in php, html, etc.

In a ideal world, the three main layers of a good-looking application (i.e., presentation, behaviour, and storage) would be clearly separated. We have tried to support this principle as much as possible with YACS. However, this (good) rule has explicitly been violated where we had to balance with simplicity.

The presentation layer

The presentation layer is devoted to php pages. No magic, no complicated template, php has been designed from the outset to do that. Create a subdirectory, put some php files in it, change the main index.php to link it to these files, and that's it.

Skins

People that want to make most of their pages look similar will use skins. Once again, there is no magic here. The basic mechanism is to declare a Skin class at the beginning of your file, to assign the page content to some variables, and to include a common php file to deliver the final rendering. To ease the process, we have created two functions. Basically, you only have to call load_skin() and render_skin() to do it. Look at the code in the main index.php, this should appear clearly.

Do you want to develop your own skin? Fabulous! As a starting point you can copy and rename files from the skins/skeleton directory. Then change the skin name through the configuration panel at control/configure.php and start to tune your new skin until success.

See also: skins/index.php

Codes and Smileys

By default text submitted to any yacs server is filtered to protect from hackers. Also, a special set of safe codes are available to beautify your posts.

See: codes/index.php and smileys/index.php

Boxes

What is static and what is dynamic in yacs? Numerous web systems are offering a administration interface to add some boxes on the left or on the right or the main index page. But yacs has no specific administration interface. Boxes are coming from ordinary items of information, articles or whatever.

During the setup of the server several sections and categories are created to hold or to flag pages that have to be put in some boxes.

By posting articles into following sections you will populate the front page of your server:

'covers' - the last published article in this section is used as the main cover of your server
'navigation_boxes' - each article is displayed into its own box on every page of your server
'extra_boxes' - each article is displayed into its own box, at the site front page only
'menus' - the last published article in this section is used as the main menu of your server

By linking existing articles to following categories you will populate some lists:

'featured' - list featured articles

See also: sections/index.php, categories/index.php (you will have to be logged as an associate to view special sections and categories)

Blogging

Well, we are quite proud of it: yacs has been fully tested with w.bloggar, and the combination is really fun and handy. Give it a try!

See also: services/blog.php, http://wbloggar.com/

Localization

What about localization? In previous developments I used to have a separate file per language to store all strings for this language. While this design has proven to be efficient, it adds a big overhead to the software developer.

In yacs, a lightweight mechanism has been selected for localization. When you need a string, declare all variations of this string, but use only one. Take a look at i18n::s() in shared/global.php to understand it. The big advantage of this design is that all languages are available at the same time. You may even have some sections of your server in english, and other sections in your native language if you want.

See also: shared/global.php

The behaviour layer

As you main know

the behaviour layer of a web server is limited to answering to un-related queries of web components. Therefore, talking about the behaviour of a web server is equivalent to discuss options on submitting requests to the server.

Addressing space

Some people have a tendancy to limit the number of scripts, and use complete sets of parameters to build dynamic pages. To handle articles, they will have a single script called articles.php. To create, edit or view an article, they may use something like 'articles.php?op=new', 'articles.php?op=edit&id=12' and 'articles.php?op=view&id=12' respectively.

We prefer to create numerous scripts with one or zero parameters. One important reason is that you have to build complete paths to let search engines index your pages extensively. To create, edit or view an article, we are using respectively: 'articles/edit.php', 'articles/edit.php/12', and 'articles/view.php/12'.

Module programming interface

Well, apart from common declarations and libraries placed into the shared directory, and of the skin stuff located into the skins directory, there is no special programming interface into yacs.

To create you own module, you will to create a new directory and to put callable scripts in it. Of course, it helps to look at existing modules to respect coding standards as much as possible.

Overlays

If, during some analysis of your needs, you end up with the conclusion that adding some fields to an article would suffice, then consider overlays as the faster track to deliver.

For example, overlays can be used to implement cooking recipes efficiently (i.e., with one single script) while retaining all feature available for articles (e.g., images, files, links, codes, etc.)

See: overlays/index.php for a more complete description of overlays

Links and Hooks

Once your scripts are running as expected, you will have to link them with other scripts, and with the site front page. The most simple action is to update the main menu of your site (section 'menus') or to add boxes with adequate information (sections 'navigation_boxes' or 'extra_boxes').

You can also use existing hooks to trigger your scripts. This is a very powerful, while straightforward, mechanism, to extend yacs capabilities. For example, the script control/setup.php has a hook to setup database tables that are not part of the basic set of yacs tables. Likely, the main configuration panel control/index.php may be extended and reference some of your configuration scripts if necessary.

See: control/scan.php for a more complete description of hooks

The storage layer

The database abstraction

Usually, we have separated most of the code related to the database in dedicated php files. This has allowed us to limit the number of scripts interfacing with mySQL.

Consider for example lists of articles. They only differ in the amount of information displayed, in the order of rows, and in the number of rows. Moreover, it is very useful to display the same list into several different pages.

To make things clearer we have created static classes to support such queries. Do you want a list of the newest articles? Call Articles::list_by_date() and you will fetch a nice array of labels and related urls.

See: articles/articles.php, sections/sections.php, categories/categories.php, files/files.php, links/links.php, comments/comments.php, images/images.php, tables/tables.php, users/users.php

Tables maintenance

The creation and the upgrade of the database schema is made by control/setup.php. This script uses PHP arrays to build adequate mySQL statement. For example, the table storing articles is described in Articles::setup(), in the file articles/articles.php.

One innovative feature of yacs is the ability to link items of information on-demand. Therefore, the database schema is simple to handle and to extend, as explained in the next paragrah.

Modules and anchors

In yacs a module is simply defined by a set of php files and by a related set of tables in the database. To build a complete page, you will refer to one or several modules by including related php files.

That's fine, but how to link modules together? Things are very easy when you are considering independant modules. However, improving the content of your web server usually requires to link the many stored pieces of information. On top of that, you would like to be able to reuse existing modules to link them to new ones with almost no modification.

This is where we have introduced anchors. In yacs, anchors are master items that are related to many sub items. Consider for example a section of your site. Hopefully this section will contain several articles. We will say that the section is an anchor. To refer to this anchor, we will use a type (here: 'section') and an id (e.g., '12'). Add a colon ':' in the middle, and you will get the full anchor name: 'section:12'.

Now that we have an anchor, it is easy to link articles to it. We simply have defined a field named 'anchor' in the article table to store anchor names, and that's it.

Six months later. You have created a brand new module named ancestors to handle genealogical data. Of course, you would like to be able to publish articles for each ancestor. How to do that? Well, you will define 'ancestor' as a new type of anchor in your system, and store 'ancestor'-based anchors in the articles table. You don't have to alter the articles table to do it.

How to retrieve items related to an anchor? Just ask for it. If you want to list articles in the section 12, select items where anchors = 'section:12'. If you want to list articles related to ancestor 34, select items where anchors = 'ancestor:34'.

How to retrieve an anchor related to an item? This is necessary to display a valid context around an item. For example, an article related to a section may mention some introductory words on the section it is in. But an article related to an ancestor may remember the salient dates for this person. Since we don't want to adapt the module that handle articles, we have built a simple interface class named Anchor. This interface, which is the only one used within the articles module, is implemented in derivated classes such as Category or Ancestor. Take a look at shared/anchor.php for more information.

As a conclusion, if you want to let items behave as anchors for other modules, you will have:

to name the type of your anchor (e.g., 'mytype')
to implement the Anchor interface in one php file (e.g., 'mytype.php')
to update the load_anchor() function in shared/global.php (e.g., on 'mytype:15', prepare the adequate SELECT statement)

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com