Welcome to ACR documentation!

• Index
• Module Index
• Search Page

What’s ACRCms?

ACRCms is an open source Python web content management system based on Turbogears and libacr. ACRCms is designed to let non technical people create and manage their web pages and thanks to its plugin system and libacr it is also easily extensible and embeddable in any web site using the Turbogears framework. The ACR project has born in 2009 as a library to be imported inside any Turbogears application to provide a way to quickly create web pages and manage their content. After releasing it as an open source project, the AXANT team thought that it would have been useful to provide an example on how to use it and created ACRCms which is a Python web content management system based on libacr.

Currently ACRCms supports:

• News and Blog sections with comments
• Image and HTML5 video galleries
• Managed storage for other file types (es. PDF)
• Plugin support
• Internal Search Engine
• Youtube Videos embedding
• Static and Dynamic Google Maps
• Twitter Integration (import your tweets)
• Content versioning
• Internationalization
• Access Control Lists
• RSS Integration (import and export content using RSS)
• Automatic form-to-mail generation

Plans for the future include theme and layout management interface and a rich set of plugins, if you want to contribute feel free to send an email to: tech [at] axant.it

Some basic information about ACR

Before starting to use ACR Tutorial you need to know some basic information about ACR.

The ACR’s structure consist in a group of “Slices” on your page.

Every slice is an html <div> element with some content inside and you can decide with one click your slice position, type ecc...

For help you to create and manage your site, every page is automatically divided into five parts: Header, Leftbar, Main, Rightbar and Footer.

Every of these five parts are a <div> in your html document.

When you want add some new contents, you just need add a new slice, write the slice’s content and decide where your slice must be positioned, for example in your header or main.

Every <div> in your document has its own class, so you can easily use them whit an external css style-sheet.

Now you’re to start reading the tutorial!

Tutorial, My first basic web page with ACR

1) First Step: Installing ACR

• Download the package from http://pypi.python.org/pypi/acr
• Extract its contents: [tar zxvf name]
• Run “python setup.py develop” from inside the ACRCMS directory. Python will download all the required dependencies and install it on your system.
• Run “paster setup-app development.ini” to get the default database instance created using sqlite.
• Now just run “paster serve development.ini” to start ACR.
• Fire up your browser and load http://localhost:8080
• Welcome to ACR!

2) Edit my Index page

The page you are on it’s your Index page, go to http://localhost:8080/login and log yourself as User:manager with Password:managepass to start editing your page. Once logged in, all the slices are updated with a menu on top, detailing the slice position and name and showing controls to edit or delete the slice. Let’s try to edit a slice:

• Find the acr_presentation menu and click on edit.

  

• You are presented with some information about the slice: name, zone, tags, page and below them the edit operation that you did on that slice. Change the slice name from acr_presentation to my_presentation and click Submit. Let’s change the slice content, now always in your slice-information page click the edit button at the bottom of the page to open up the slice editor tool.

• Here you can edit the slice’s content, according to its type, for example, this one its an HTML slice, so you are presented with your HTML code.Now, you have two options, if you need write only text you can do it on the editor but if you need some html code you must push on html button and write all text here. In this case, let’s try click on html button, a new window will open, here erase the current content and then type “Hi, this is my first ACR presentation slice!”. Finally, click the Save button.

  

• You’re now back at slice edit menu, click on Back to web page at the top of the page to return to your modified Index.

3) Add a new slice

We’ve seen how to edit a slice, let’s now try to add a new one.

• Click ADD SLICE at the top of the page, then select what slice-type you want to create, for example HTML.

• The slice edit menu will show up, add a name Name to your new slice, for example testslice.

• Select where you want to show the slice, for example main.

• Skip the tags section for now and write your content. (Important! It’s an html code, so remember, you need write it on html window).

  <h1>My first slice!</h1>
  <p>This my first slice's content.</p>

• Click the Update button and then Save.

• You’re back to your Index page, that now contains also your new slice.

  

4. Add a new page

We’ve seen how to create and update a slice, now it’s time to create a new page.

• Click the ADMIN button at the top of the page.

• The ACR Administration page shows up: click Create Page.

  

• The new page edit menu shows up: fill in the title and URI of your page, for example we will use Gallery as title and gallery as URI. Click Submit and you’ll be redirected to your new page, on which you can create slices.

  

You learn now the basic ACR options to edit, delete, add slice and page, let’s try now to create a basic web site with Index, Gallery and Contact page.

5. Create a Gallery page

Now, before create your gallery you need to know what we need for do it. We must upload the images, give to all of them a Tag and then create a new Image Gallery, but don’t worry we’ll see step by step.

• Click the ADMIN button at the top of the page.

• Click Manage Tags, then give to your new tag a name, for example gallery_image and create it.

• Now click Back to dashboard at the top of the page and click on Remote Disk.

• Click the Upload button and the image.

  

• Now, let us see what to put in each field:

  • Click the Browse button and search an image to upload(png, jpg and gif are the format allowed).
  • Don’t touch Page and Path fields.
  • Now you must tag your image with the tag that we created, so select gallery_image from the list.
  • Give a title to your image.
  • Leave “auto” in Size field and “no” in Show Title and Show Description fields.
  • You don’t need a description so leave your textarea empty and click Save.

  

• You’ve uploaded your image on the rdisk, now do it again with other two images, remember to tag also them with gallery_image.

• Now you should have uploaded all three images to the rdisk, click to back to dashboard.

• Search under Templates menù, “Create Image Gallery” option and click on it.

• In this page you need to decide in what page insert the images, in this case select “Gallery”, in Members Tag field select your tag that you give to all your images, gallery_image, then click to Create.

• Click Back to Web page at the top of the site and go to Gallery page to see your result, if you follow all the istructions you should have all three image(obviously they should then be stylized with CSS).

  

6. Create a Contact page

You already know how create a new page, so do it.

• In your contact page add a new slice, the slice type must be “FORM”.

• Now, let us see what to put in each field:

  • Give a name to your form.

  • Select the zone of your form (usually all forms are in main zone).

  • We don’t need to tag it at the moment.

  • In Destination Email field you should put the email address where the form must send the email, now put your email address on it.

  • Choose the email Subject.

  • Now you must write the form content with the right sintax. You can use text, textarea and select in this way.

    LabelName=text
    LabelName2=textarea
    LabelName3=[Option1, Option2]
    
    For example write:
    
    Name=text
    Letter=textarea
    Sex=[Male, Female]

  • On “Save with tag” choose do not save for the moment.

• This is now your form!

• Push Save button and you’ll see your form!

Congratulation, you’ve created your first website!

Tecnical Documentation

ACR Dashboard

This section will explain you in detail the various functions of ACR.

Under this section you find all the basic functions for managing your site.

• Create Page

  When you create a new page you need give to ACR three informations: Parent Page, Uri and Name.

  Parent: Here you can tell to ACR if this new page will be a child of another page or not, if it is then select his parent from the list.

  Uri: Here you can decide the path page name, you can use all name you want but is recommended use something similar to the page name.

  Title: Here you can give a name to your page, it isn’t linked to the Uri, but it is advisable to use a similar name.

  Here an example of how create a new subpage of Gallery:

  

  Now press the Submit button and you will have created your new page!

• Manage Pages

  This menù is tha same of Create Page, under the Create Page menù you can see all pages in your site, here you can easily delete or edit them and their contents.

  This is the table that you have:

  

  Action: You can choose if delete or edit a page.

  Url: All pages url.

  Title: All pages title.

  Slices: You can see all slices in that page.

  Languages: This is the page’s language, it’s automatically selected in accordance with the language of your browser.

  Authors: Who create the page.

• Manage Tags

  Tags are a powerful tool to control the behavior of HTML elements and slices on the page.

  Tags may be associated with the slices. Each slice can have an infinite number of tags associated to it.

  When you give a tag to a slice, your HTML code automatically associated to the div container of a slice a class that takes its name from the tag like this:

  “acr_tag_TAGNAME”, where TAGNAME is the name of the tag.

  In a nutshell, using tags you can easily write CSS rules for every slice you need and many other things.

• Remote Disk

  Your remote disk is simply your unit of storage where you can upload file, video or image and also make a directory.

  

  This is an example of what you need to know to upload an image and fill the required fields.

  • File: You can choose your image pressing Browse button.
  • Page: You can choose if you want only upload it on your RDisk or put it on a page.
  • Path: You can choose if upload your image on a specific directory on your rdiks or not.
  • Tags: You can choose if give some tag to your image.
  • Title: You can choose your image name.
  • Size (auto or 320x240): You can choose if resize your image or not.
  • Show Title: You can choose if show image title on top or under it or don’t.
  • Show Description: You can choose if show the image description or not.
  • Description: You can write a description for your image.

  That’s all you need to upload without problem your image or everything else.

  

Templates

Under this section you find all the additional features that you can add to your pages.

• Uservoice Feedback Tab

  With this function you can add a feedback service to your page.

  First thing you have to be registered on Uservoice.

  Now go to Uservoice Feedback Tab menù and choose in which page insert this service(if you choose default page all pages will have it), then put the name you choose for your forum URL(eg. forum.uservoice.com where forum is your key).

• Tabs

  MISSING

• Insert YouTube Video

  This function is very easy to use and allow you to add a youtube video on your page.

  You only need choose in what page insert it and video url.

• Create News Section

  MISSING

• Create Slideshow

  Whit this function you can add a slideshow of images in your pages, let’s see how to do step by step.

  • First thing to do, create a new tag, for example slide_image.
  • Select for example, two images, with the same size and upload them on your remote disk. (Important! Do not enter into any page and give them slice_image tag)
  • Now go back to dashboard and click on Create Slideshow.
  • You just have to choose in which page insert your slideshow, select the tag you just created and decide which effect give to your slide. (Problem! At the moment when you add your slideshow unfortunately it doesn’t show up, you must go to edit it’s CSS rules and give a dimension to container div depending on the size of the images, for example “height: 140px”)

• Accordion Gallery

  With this function you can create a new accordion of image, for understand better what is it, just try!

  Let’s see how to do step by step.

  • First, create a new tag.
  • Select the images you want in your accordion(the images should have the same dimension), upload them on your RDsik and give them your new tag.
  • Now go into Create New Accordion Gallery option and choose in which page insert your gallery and your new tag. If you want you can set the accordion dimension.

• Create Image Gallery

  With this function you can create a new gallery of images, let’s see how to do step by step.

  • First, create a new tag.
  • Select the images you want in your gallery, upload them on your RDsik and give them your new tag.
  • Now go into Create New Photo Gallery option and choose in which page insert your gallery and your new tag, that’s all!

  Whit CSS you could easily modify your gallery style.

Themes

Under this section you find all the additional features that you can add to your pages.

• Edit Css

  Here you can directly edit the CSS of your site.

• Manage Themes

  Here you can select which ACR Theme uso for your site and setup it.

• Upload Theme

  Here you can upload new ACR Themes.

General Settings

Under this section you find the general setting for your site.

• Add Google Analytics

  With this function you can easily add Google Analytics service to your site(Google Analytics (GA) is a free service offered by Google that generates detailed statistics about the visitors to a website).

  First you you need to sign up to the service on Google Analytics, then it will give you a code to insert in every page like this:

  <script type="text/javascript">
     var _gaq = _gaq || [];
     _gaq.push(['_setAccount', 'UA-21448313-1']);
     _gaq.push(['_trackPageview']);
     (function() {
        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
     })();
  </script>

  But with Add Google Analytics function you can avoid all this. You only need put the UA-code(for example on the code above is UA-21448313-1)in the field and then your site will be immediatly present on this service.

• Google Maps

  Here you can activate the option to add some google maps on your page.

  You only need go to here read and agree with the terms and conditions, put your web site URL and then press Generate API Key.

  Then go at top of the page and copy the first code, something like this:

  ABQIAAAAbhOln6rjaY341cjE0clchxSVSdWGKayNFaHQCvrMitWKZ-4ysxQGgzfqdDDmYZxn7BOMejqG8k5xMQ

  Now go to Google Maps option on your ACR dashboard and put that code in the field.

  You can now add Google maps on your pages. To learn how read ADD MAP SLICE section of this documentation.

• Disqus

  Here you can activate a Disqus service for your site.

  You only need go to Disqus, register and then put your Disqus User ID on the field.

• Change My Password

  Here you can change your admin password.

Advanced

Under this section you find some advanced function about your site.

• Add User Defined Views

  This is a powerful feature that lets you create custom views to facilitate the addition of specific slice.

  You can for example create a new view that allow you to insert comment with name, surname and email adress.

  When you go into this option you have this fields to fill:

  • Name: Give a name to your slice.

  • Code: You must write the html code that should be create when you add a new comment slice, for example:

    <div>
       <b> ${name} </b><b> ${surname} </b>
       <p> ${comment} </p>
       <i>From email:</i> <b> ${email} </b>
    </div>

    For insert some variable words you must use ${VarName}

  • Fields Definition: You must write all variables that should appear on your html code, preceded by the constant [fields], for example:

    [fields]
    name=text
    surname=text
    email=text
    comment=html
    

  

  Now go to your page and under ADD SLICE you’ll find your new slice type, add comment, click to it.

  How you can see, the creation menu have all fields you need, name, surname, email and comment. Fill all fields, submit and see you result that should be something like this.

  

  In other words, you can create a custom creation menu for custom slice type.

• Manage User Defined Views

  Here you can edit the User Defined views already created.

• Manage Slice Groups

  Here you can create new Slice Groups(like Gallery slice group) and manage them with some options like order, preview etc...

• Unbound Entities

  You can find all the entities (images, files, slice) that you have created but are not currently present on any page.

• Users Permissions

  MISSING

About the structure

The following will explain in detail the structure of ACR and how it works.

Content - View - Slice - Page

Starting from the top, each page created by ACR consists of a set of slices.

As we mentioned at the beginning of this document a slice is a piece of html page that displays some contents in a certain way.

Each slice displays its contents following his precise template that is specified in his view.

A view is a Python file that create the right html code for show our content, then we can say that every slice has a specific view and that each slice is the result of a view with a content.

Now we know that our slice displays its content according to his view but what about our contents?

When we create a new slice, we insert content(text, images etc...) that it will display and automatically will be created two new files in our database which we will call Content(.ini file format) and ContentData.

The same content can have multiple versions and can be written in different languages, so we will have a different ContentData file for each version or language of such content as you can see in the image above.

In short, in our Content file we have all the addresses of every ContentData associated with that content so that our slice can retrieve and display the correct version and language of our content.

We can sum up everything in this simple diagram:

Tags

ACR provides another great feature, we’re able to tag each slice.

When we do this, the html code automatically adds a new class to the div containing the slice, in this way we can easily manage it with CSS but not only, the slice now is marked with that tag so if we mark more slices we can easily create a SliceGroup.

A SliceGroup is a new slice that show all the slices with the same tag, for example can be useful to create a Image Gallery where each Image is a single slice tagged with the same tag and a slicegroup show all of them.

Views

Specifically, there are three different types of views.

Python Views: These are the default basic views that ACR provides to you so can use to create your page.

User Defined Views(UDV): If the basic views are not enough to show your content as you want ACR allow you to create a custom-type view choosing what content to include and how to display them.

View Construction Kit(VCK): —