Welcome to MySmile’s documentation!

Contents:

Getting started

Overview

MySmile is the lightweight open-source CMS based on Django. It helps to create websites with configurable design and minimum cost. MySmile is best choose for:

  • Small websites aimed on static content with limited dynamic. For example such: “Startup business”, “Personal site”, “Conference”.
  • Some prototypes/ideas that now looks tiny but has enormous potential to grow. Because MySmile use Django framework it breaks all barriers for implementation your new features.
  • Freshmen Python developers for studying and experimenting.

Innovation MySmile features:

  • Use newspaper text organize technology like: columns, incuts.
  • REST API helps construct mobile and desktop application
  • Moreover REST API client is available, for now it is php client with examples and unitTests
  • Design can be modified by admin panel without any additional program coding.
  • There are more then 27 unique designers combination! How we get them? Let’s look into calculation. Every page consists of the 3 parts: central-column, right-column, bottom-column. Right-column can have 3 columns. And right-column has also 3 components: photo, youtube, text. Additionally every element can or can’t be present.
  • Additional menu is creating dynamically from pages that is present inside of page as a link. It works like mix of “cloud of links” and “bread crumbs”. So you open links and it’s on the menu.

Source code is available on GitHub.

Get the latest version with the command: $ git clone --branch=master git@github.com:MySmile/mysmile.git

See unstable development version: $ git clone --branch=dev git@github.com:MySmile/mysmile.git

Please read this documentation or try http://demo.mysmile.com.ua/ for more information.

Quick install guide

It is assumed that the python version 3.x and bower are already installed on your computer.

  1. Download MySmile and unpacked to the project’s directory
  2. Install with one command: $ make install
  3. In the project directory run a command in the terminal: $ python3 manage.py runserver

Now your website is available on http://127.0.0.1:8000, link to admin page is http://127.0.0.1:8000/admin. Log in with default credentials:

  • login: test
  • password: test

Technical specification

Objective

MySmile is the lightweight open-source CMS based on Django. Project focus on context, usability and SEO. It is aimed particularly to small site that provides information about person or business. It is something similar to Blog and Homepage. Information of such site does not change so often as in Blog but more then on Homepage. In other side MySmile can be extended for the way as you want.

MySmile includes:
  • Admin panel for content managing
  • SEO: friendly url, meta, HTML5 semantic, Google analytics, etc
  • Flexible design configuration
Example of site structures that MySmile will be a best choose:
  • Small business site with pages: “Main”, “Products”, “Technologies”, “Partners”, “Contacts”.
  • Personal site with pages: “Main”, “Education”, “Hobbies”, “Contacts”.
  • Conference site with pages: “Main”, “Schedule”, “Speakers”, “Accommodation”, “Contacts”.
  • Quick start of Python and Django.
_images/site_diagram.png

Features

Fundamental features:

  • Internationalization and localization
  • Google Analytics is connected
  • Sitemap.xml is generated on fly
  • Two fully responsive themes out of the box
  • Switching between the themes from admin
  • User interface that “Don’t make me think”
  • Additional dynamic menu like a mix of “cloud of links” and “bread crumbs”
  • REST API with REST API Client on PHP, Java, Python
  • Unlimited number of pages

SEO features:

  • HTML5 semantic
  • Sitemap.xml
  • Robots.txt
  • Friendly Urls
  • Meta tags
  • Alt attribute for images

See also

SEO configuration

Technology

Project’s part Technology
Language Python 3.x
Framework Django 1.8.x
Database SQLite 3
Frontend HTML, CSS, JS framework like Bootstrap or Pure CSS
Documentation Sphinx

Also used third-party components:

  1. JSColor as colorpicker in admin
  2. Bootstrap, Pure CSS into themes.

Database schema

Database schema is designed with a MySQL Workbench. It is available here.

_images/database_schema.png

Urls

URL is user friendly based on unique slug. Valid characters for slug are alpha numeric and hyphen to join words.

For instance: http://mysmile.com.ua/en/about-company.html

Content

All content can be changed via the Admin panel.

Page parts

Part name Description l18n Required Unique
Menu It is important to choose simple short name. It is used for menu. yes yes no
Name It is title of article. If it is not set “Menu” is used instead. yes no no
Central Column Central column of the article yes yes no
Right Column: Text Right Column of the article. Central column of the article yes no no
Right Column: Multimedia Photo or video that available in the Right Column no no no
Bottom columns Columns in the bottom side of the article. There are only 3 or less bottom columns yes no no

SEO configuration

Search engine optimization (SEO) is presented as configuration parameters. Table bellow describe properties of such options.

Property Description I18n Required Unique
Meta tags Title, description, keywords, photo description yes yes no
Slug Part of URL. All spaces and other non alphanumeric characters are changed to underscore. no yes yes
Right Column, Photo Alt property of <img> tag yes yes [1] no

Footnotes

[1]If Photo available

See also

Google recommendation for SEO.

Technical configuration

Property Description I18n Required Unique
Statuses draft, published no yes no
Page type Menu page, inner page, api page, api&menu page no yes no
Date of creation Date of creation page no yes no
Date of modification Date of last modification page no yes no

Preferences

Preferences contains information of contact and general technical information. All of them can be changed from the Admin panel.

Name Default value Description
Skype myskype  
Email [1] myemail@email.com  
Phone number 000 000 000 00 00  
Turn on/off REST Api True  
Max number of inner pages [2] 3 Number of pages that can be shown under main menu when user follow links inside page.
Google Analytic code 000000  
Image quality 70 Global setting quality uploaded pictures. The picture quality is directly proportional to the size of the file. A value of 100 corresponds to the maximum quality.
Image autoscale True Global setting for autoscale uploaded pictures if its width>333px. Pictures will be scaled to width=333px.
Theme modern Choose a theme for switch

Footnotes

[1]E-mail is automatically converted to the image for protection against spam bots.
[2]Number of pages of type inner page may be infinitely.

See also

Technical configuration.

Admin panel

All content can be changed via the Admin panel.

Overview

Multilingual admin panel is available http://127.0.0.1:8000/admin/

  • Username: test
  • Password: test
_images/admin1.png _images/admin3.png _images/admin2.png _images/admin4.png

Language localisation

Add another language with option LANGUAGES in mysmile/settings/base.py. For example, this language will be Polish. Create directory pl into directory mysmile/locale/

Run command:

$ make makemessages lang=pl

Open and translate files locale/pl/LC_MESSAGES/django.po, then run::

$ make compilemessages lang=pl

Themes

Available themes

Two fully responsive themes out of the box.

Classic based on Pure CSS

_images/theme_classic.png

Modern based on Bootstrap

_images/theme_modern.png

See also

How to add a new theme

Configurations of theme

Property Description I18n Required Unique
Color Color of active menu and vertical line on left side. Each page can have its own color vertical line on left side. no yes no

Note

Property Color use in classic theme only

How to add a new theme

The new theme can be added manually by placing files in the appropriate directories

  • apps/pages/templates/themes
  • mysmile/static/themes

In this case the name of new theme is added automatically into admin panel. Switching between themes can be done using the preferenses.

How to create a new theme

The new theme is created from any available template, which can be downloaded from the Internet.

REST API

REST API v1

This is version API based of Django.

Objective

REST API provides access to MySmile data. As a result it makes possible to create alternative UI design based for instance on AngularJS or even use as a part of Wordpress. For such purpose PHP and Java clients were created (Python client is on a way).

Configuration

REST API is configurable feature in the MySmile project. Therefore to turn on/off it is need to change Preferences configuration parameter.

Endpoint

Endpoint of api is http://mysmile.com.ua/api/.

Methods

MySmile api is support only /GET method.

General parameters

List bellow show required parameters that have default values. It means that if they are not present in request that default value are going to be used.

Format

It sets format of request/response. Currently it is supported JSON but for future other types will be acceptable XML or JSONP.

parameter name value default
format json json
Version monitoring

Parameter that shows what version of api is used.

parameter name value default
v 1 1

Note

This parameter is not used now. It is reserved for in future need for version migration politics.

Language

Parameter that sets language of response.

Parameter name value default
lang en en [1]

Footnotes

[1]The default value is the first order LANGUAGES from settings/base.py

Request

Request format is: endpoint + resource + required parameters. General parameters can be omitted because they have default values. For instance request to get content with slug home in json format with en language:

/content?slug=home&v=1&lang=en&format=json

The same but with omitted general parameters:

/content?slug=home

Request to get list of all contents:

/content

See Examples for details.

Response

Response contains code and body (accordingly HTTP specification). Body has duplicated HTTP code value.

JSON
Success

General format of success response is:

{ code: 200, data: {array or object} }

Example:

{ code: 200, data: ["home", "about", "price", "contact"] }
Failure

General format of failure response is:

{ code: HTTP code, msg: "Error message" }

Example:

{ code: 500, msg : "Internal server error" }

Resources

Those parameters should be presented in the every request otherwise default values will be used.

Content

That resource returns content of current page by slug or list of available contents if slug is not set.

Resource GET [1] Example
/content list of contents 
{
  code: 200,
  data: [{"home":"Home"},
        {"about":"About"},
        {"contact":"Contact"}
      ]
}
/content?slug=foo current content by slug 
{
  code: 200,
  data: {
    menu: "Home",
    name: "name of central column",
    col_central: "html of central column",
    col_right: "html of right column",
    col_bottom: [
      "html of first bottom column",
      "html of second bottom column",
      "html of third bottom column"
      ],
    youtube: "link to YouTube resource",
    photo: {
          src: "url to photo",
          alt: "alt text",
          description: "description"
    }
  }
}

Footnotes

[1]For other HTTP methods API response will returned error with 405 code. For more information please see Errors section.
Language

That resource returns list of available languages.

Resource GET Example
/language list of supported languages 
{
  code: 200,
  data: ["ua","ru", "en"]
}
Contact

That resource [1] returns structured contact information such as phone, email, skype.

Resource GET Example
/contact list of contact data 
{
  code: 200,
  data: {
    email: "test@mysmile.com",
    phone: "111-11-11",
    skype: "mysmile"
  }
}

Notes

[1]Parameters of response configurable through MySmile settings table in database (since v 0.5.0 of api sever).

Errors

HTTP code Description Example [1]
403 Request was a valid one, but server was refusing to respond to it. 
{ code: 403,
  msg: "Forbidden"
  }
404 Resource not found. 
{ code: 404,
  msg: "Not Found"
  }
405 A request was made of a resource using a request method not supported by that resource. Try to get access to POST if only GET available. 
{ code: 405,
  msg: "Method Not Allowed"
  }
500 A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. Error in the code or invalid parameters use. 
{ code: 500,
  msg: "Internal Server Error"
  }
501 The server either does not recognize the request method, or it lacks the ability to fulfill the request. Resource does not implemented 
{ code: 501,
  msg: "Not Implemented"
  }

Footnotes

[1]Error messages should be only in English.

Examples

Request/GET http://mysmile.com.ua/api/content?v=1&lang=en&format=json
Response/Code 200
Response/Header Content-Type application/json;
Response/Body 
{
  code: 200,
  data: [{"home":"Home"},
         {"about":"About"},
         {"contact":"Contact"}
        ]
  }

Frequently Asked Questions

Can I use the MySql database instead of SQLite?

Yes. To do this, do the following:

  1. Run $ pip3 install pymysql==0.6.7

  2. Add into manage.py this lines befor line if __name__ == "__main__"::

    import pymysql
pymysql.install_as_MySQLdb()

  3. Set Django DATABASES settings in config/local.py like

    DATABASES = {
  'default': {
      'ENGINE': 'django.db.backends.mysql',
      'NAME': 'mysmile',
      'USER': 'root',
      'PASSWORD': 'password',
      'HOST': '127.0.0.1',
      'PORT': '3306',
  }
}

  4. Create database mysmile

  5. Run command $ make newdb

  6. Run local server $ make run

Glossary

additional menu

Additional menu is a dynamic navigation that is generated from inner pages after lasts were visited. Configuration key “MAX_INNERLINK_HISTORY” set a max number of such pages in menu.

See also

Preferences.

api page

Api page is specify pages that are available only from REST API.

See also

Technical configuration.

api & menu page

Api & menu page is an combination of api page and menu page.

See also

Technical configuration.

inner page

Inner page is characterised pages that used as link inside of menu page. Such kind of pages are not part of main menu but from visited inner pages are formed the additional menu.

See also

Technical configuration.

menu page

Menu page is described pages that are shown in the main menu.

See also

Technical configuration.