This article describes the basic functions of the Site application by an example of a simple website powered by two apps: Site and Blog.
1. Creating a website at mydomain.com
To create a website, add its main URL to the website list (displayed in the top left corner of the Site app). In our example we shall not add a new site, because the main domain name mydomain.com was automatically added to the list during the installation of Webasyst:
The website is already operational and you can view it by opening the root URL of your Webasyst (in this case it is http://mydomain.com/):
Now the entire website consists of only one demo page "Welcome!" and utilizes the default design theme named "Default". Let us add the sections: "Blog", "Shop", create a new web page, and try to slightly modify the website design.
2. Routing and Application Settlement
The main structure of a website is defined by its routing settings: special rules distributing the entire address space of a website among the installed Webasyst applications. Open the routing settings screen:
Now there is only one routing rule: mydomain.com/* -> Site. This rule means that the entire address space is handled by the Site application, i.e. any request sent by a website visitor will be passed on to (in other words, routed by) the Site app for further processing.
Let us add, as shown in the picture above, new rules for mydomain.com/blog/* -> Blog.
We have settled the Blog app at mydomain.com/blog/, so any URL based on
mydomain.com/blog/ (e.g., /blog/2011/?tag=updates,
/blog/announcements/new-app-released/, etc. — this is specified as an asterisk * in the routing rule)
will be routed to the Blog app. All other URLs not satisfying the rule mydomain.com/blog/* will be routed to the Site app according to the last (default) rule.
In this and other documentation articles the term "settlement" is used to determine the URL-based location of an application connected to the website by means of a routing rule. This term is rather informal, but it very well reflects the idea of connecting an application to a certain group of URLs.
Please note that rule /blog/* is specified above rule /* in the routing settings, because rules are analyzed one by one exactly in the same order in which they are displayed, and the first rule matching the current user request is triggered; all remaining rules are ignored. If we had moved rule /* above rule /blog/*, then rule /blog/* would have never been triggered at all, because a more common rule /* would always satisfy any user request. The more common is a rule, the lower should it be placed in the rule list.
In the main (top) menu of the website (frontend) new link "Blog" has appeared, which allow you to open web pages generated by the corresponding applications:
Link anchor "Webasyst" in this case is retrieved from the Webasyst installation name (your company name) specified in the Installer app's settings. If you had a different name entered in that settings field, it should automatically appear instead of "Webasyst" in the website's main menu. Whatever the case, you can change this title in the app's settlement settings.
3. New page
Let us add a new page "About us" to be accessible at mydomain.com/about-us/:
The page will appear in the left-hand menu of the main website section (/*):
The page-management mechanism allows you to define a hierarchy by dragging page titles to the desired positions. The maximum nesting level of pages is not limited.
4. Blocks
Now we shall add another page "Feedback" with an email-sending form. This is possible with the help of a standard request-sending block provided by the Site app (messages are sent to the email address specified in the settings of the Installer app. Go to section "Blocks" and copy the code to embed block send.send_email_form:
Create a new page named "Feedback" and embed the message-sending block in its layout:
This is how such a page looks in the website's frontend:
The functionality of blocks allows you to integrate frontends of different applications with each other by embedding content generated by some of them in the design templates of the others. In the backend you can edit the layout of blocks, use Smarty, and create your own blocks.
5. Design
Now we shall slightly customize the website design, which is currently provided by the frontend's "Default" theme. Select the Site app in the left-hand column
and apply changes to design templates sidebar.html, index.html, and
default.css (changes have been made for illustrating purposes only; in the screenshot only a part of the changes
in file default.css is highlighted, other changes are not shown).
Save your changes and open the website:
At the moment when you were saving changes in sidebar.html (or in any other template file), the Site app automatically
copied the "Default" design theme (which was originally located in wa-apps/site/themes/default/)
to folder wa-data/public/site/themes/default/. From now on, all changes made to the templates of this design theme
will be saved inside wa-data/, which guarantees that user data are preserved when themes and apps are upgraded by means of the
Installer app (during an upgrade of a Webasyst application only the originla theme version is affected in folder wa-apps/, to which you can
"roll back" at any time, and the working copy of design templates currently used on the website remains unchanged in wa-data/).
Read more about the structure of design themes in the dedicated article.
Now try to click on the "Blog" link of the website main menu. Note that changes made to design templates have not affected the pages provided by the Blog app. In spite of the fact that originally the frontends of Site and Blog looked in a common style, they are operating independently and utilize different design themes and CSS styles. To apply common design to web pages provided by both apps, it is necessary to make similar changes to the design templates of both Site and Blog.
Independance of design themes of different applications without the necessity to adjust them to global pre-defined layouts is a fundamental characteristic of the website and application development process using Webasyst, which significantly differentiates WebAsyst from many traditional CMS's. This independance allows application developers to flexilbly design their applications without being limited by any restrictions "inherited" from other applications.
6. One more settlement of the site application
Let us create one more settlement for the Site app at mydomain.com/shop/
... add a new page at the root of this URL (failure to do so will result in the 404 "Page Not Found" error returned at an attempt to access mydomain.com/shop/:
The new settlement, like the first one, also utilizes the "Default" theme by default; therefore, the new page accessible at mydomain.com/shop/ has the same look as other website pages:
The newly added page "Coming soon" will not appear in the page list of the root website section ("Webasyst"), because it is attached to another Site app settlement at a different URL: mydomain.com/shop/.
Now we shall try to modify the design of only one website section at mydomain.com/shop/ (only the new settlement of the Site app at mydomain.com/shop/) without changing anything in the "Main" website section. To do so, we have to create a new design theme and apply it to the new selected settlement by leaving the existing theme and settlement mydomain.com/* unchanged. Create a copy of the design theme in section "Themes settings" of the Site app's backend:
New theme's name is "Default 1", which you can change here using menu item "Rename". We shall leave it unchanged and shall select the new theme in the settings of the Site app settled at mydomain.com/shop/:
Now, to make our changes even more illustrative, we shall apply some modifications to the new theme's design template (in file default.css
of theme "Default 1"), which will result in the web page looking like shown in the picture below:
Now two pages of the website frontend accessible at mydomain.com/ and at mydomain.com/shop/, which are powered by the same Site application, look differently.
7. $wa->apps()
Note that in the above examples adding a new routing rule caused the new item appear in the main website menu. This was a result of a website setting,
which automatically generated the $wa->apps() navigation array:
$wa->apps() is an array, which should facilitate the website building process. It is used in design themes to generate the deafult navigation
menu and is actually a link between the routing settings and the website navigation links. Whenever a new routing rule is added in the settings, a corresponding
link appears in the website menu.
If you need the menu structure to be different from that of the routing rules (e.g., if your website has a complex structure or if only some of the available items
should be included in the menu, etc.), then you can easily "detach" the $wa->apps() archive from the current routing settings
by switching to the manual configuration of the website navigation menu:
Array $wa->apps() is supposed to help you faster create a website, but its use is not a requirement. Depending on your needs,
you may choose to either use the automatically generated or manually defined contents of array $wa->apps(), or not to use it at all
and to specify the desired navigation menu directly in your HTML templates or common blocks.
8. Cheat sheet
In design templates and in info pages you can use all functions provided by the Smarty engine. In the bottom-right corner there is always a cheat sheet containing the list of all basic available variables and methods.
As an example, we shall display a welcome message and information about the user's operating system for authorized visitors:
See how it looks in the frontend.
Tools offered by the cheat sheet can be used both in simple info pages and in design templates of all Webasyst applications.