Aldryn Documentation. Release Divio AG

Transcription

1 Aldryn Documentation Release Divio AG April 09, 2015

2

3 Contents 1 Getting Help 3 2 Table of Contents Sites Cloud Client Addons Boilerplates Themes Workflows for Agencies FAQ Glossary i

4 ii

5 Attention: This guide is currently under heavy active development. If you d like to help, fork us on GitHub! Aldryn is an easy to use and developer friendly content management system for web professionals. It goes full circle by assisting with many aspects the web project lifecycle. Providing hosting, content management, Addon-development, dependency management, product lifecycle and shared team access. This documentation provides a high level overview of what Aldryn has to offer. Then goes deeper into topics that are typically used by: Project Managers Content Creators Web Developers (frontend and backend) Contents 1

6 2 Contents

7 CHAPTER 1 Getting Help Having trouble? We d like to help! Try the FAQ it s got answers to many common questions. Looking for specific information? Try the genindex, modindex or the detailed table of contents. Search for information in the archives of the Aldryn Q&A group, or post a question. Ask a question in the #aldryn IRC channel. Report bugs with Aldryn in our issue tracker. Contact us at support@divio.ch for commercial support. While this document is focused on code for the aldryn platform, many things also apply to general django projects and apps. 3

8 4 Chapter 1. Getting Help

9 CHAPTER 2 Table of Contents 2.1 Sites Custom Domains Enter your custom domain on the general settings tab on the controlpanel. Then point your DNS to your site url.: CNAME my-site-name.us-iad-rs.aldryn.net Here are instructions on adding DNS-records for some popular DNS providers: why a CNAME record? We recommend using a CNAME record since the IP of your app might change over time. With a CNAME these changes just work. If you choose to use an A-record you ll have to manually adjust DNS settings in case of an IP change. 2.2 Cloud Client Commands The aldryn client has various commands to help you with apps and boilerplates: aldryn login - starts the login process, you will need to be logged in to use most of the commands aldryn boilerplate upload - uploads the selected boilerplate to aldryn 5

10 aldryn boilerplate validate - validates the selected boilerplate for errors aldryn addon upload - uploads the selected addon to aldryn aldryn addon validate - validates the selected addon for errors aldryn sync [--sitename=<sitename>] - synchronises a site to your local hard disc so you can edit files locally aldryn sites - shows a list of all sites django CMS Cloud Client Warning: this is just a dump from the old README.rst of aldryn-client. needs cleanup. Warning: titles depth is wrong Warning: don t repeat stuff from addons/boilerplate section. here we should cover basics like login and link to the other sections. Installing pip install aldryn-client Using the client After installing, you ll have a command line tool called aldryn at your disposal. Running it with no arguments will give you all possible commands. Logging in Before using the client, you need to log in, call aldryn login and provide your username and password. This will store a token in your local.netrc file that will be used for subsequent requests. Apps see Packaging and Sourcecode 6 Chapter 2. Table of Contents

11 Settings If you want to provide settings (and a nice form) for your app, you may add a file aldryn_config.py to the root of your app (next to setup.py). This file must contain a class named Form which must subclass aldryn_client.forms.baseform. The Form class may contain any number of form fields. Available fields are: aldryn_client.forms.charfield aldryn_client.forms.checkboxfield aldryn_client.forms.selectfield aldryn_client.forms.numberfield aldryn_client.forms.staticfilefield All fields must provide a label as first argument and take a keyword argument named required to indicate whether this field is required or not. CharField may optionally define max_length and min_length arguments. SelectField takes a list of tuples (Django style) as required second argument). NumberField has optional min_value and max_value arguments. StaticFileField takes an optional extensions argument which is a list of valid file extensions. Generating settings To generate settings, define a to_settings method which takes two arguments: The cleaned data of your form and a dictionary of existing settings (which contains MIDDLEWARE_CLASSES). Add the settings you want on to the settings dictionary and return it. Custom field validation If you want to have custom field validation, subclass a field and overwrite it s clean method, which takes a single argument (the value to clean) and should return a cleaned value or raise aldryn_client.forms.validationerror with a nice message as to why the validation failed. Custom Runtime APIs CMS Cloud apps can use special APIs to inject content into templates (either in the head or at the end of the body) from Python. Those APIs are: cmscloud.template_api.registry.add_to_head to add content to the head. cmscloud.template_api.registry.add_to_tail to add content to the end of the body. If you re using those APIs, you probably want to do so from a models.py file. Commands The client has two commands to work with your apps: app validate, which checks the app.yaml config and app upload which uploads your app Cloud Client 7

12 Boilerplates Boilerplates are a set of default templates and staticfiles, optionally with initial data. To get started, create a normal Django (CMS) project and develop your boilerplate. When you re happy with how it looks and optionally added some default content, you can transform this into a boilerplate. In your base template (or base templates), you must include the variable {{ TEMPLATE_API_REGISTRY.render_head }} in the head section of your HTML, and {{ TEMPLATE_API_REGISTRY.render_tail }} just before the closing </body> tag. Further, your base template must include the {% cms_toolbar %} template tag right after th opening <body> tag (make sure you {% load cms_tags %} first). Also, you must include two sekizai namespaces, {% render_block css %} in your head section and {% render_block js %} just before the {{ TEMPLATE_API_REGISTRY.render_tail }} variable. Now add a boilderplate.yaml file to the root of your project (next to the static and templates folders). The boilerplate.yaml must be present to upload a boilerplate to the CMS Cloud! It requires at least the following keys: name: The name of your boilerplate version: The version of this boilerplate (must be compatible with LooseVersion) description: A description of your boilerplate author: An object with the the following keys: name: Your name! url: URL to your website (optional) license: An object with the following keys: name: Name of your license (eg BSD) text: Full text of the license (pro tip: use!literal-include <filename>) templates: A list of tuples in the form of (template_path, verbose_name). The template_path is the path to the template as used by Django. The verbose name is what users will see. Including initial data To include initial data in your boilerplate, add aldryn_client to your installed apps in your project and call the management command aldryn_dumpdata <outfile> <language>. <outfile> must be a file named data.yaml located next to your boilerplate.yaml file. <language> is the language code of the language you want to include ( en is a good default choice). Only one language can be included. Handling relations in plugins If your plugins include relationships to other models that need to be included, define a setting ALDRYN_DUMPDATA_FOLLOW which is a list of strings in the form of PluginName.relationship_field. Commands The client has two commands to work with your boilerplates: boilerplate validate, which checks the boilerplate.yaml config and boilerplate upload which uploads your boilerplate. 8 Chapter 2. Table of Contents

13 Local File Sync You can sync your files locally using the sync command. This command optionally takes an argument --sitename=<sitename> to specify which site to sync. This argument must be set the first time you use the command, on subsequent calls in the same directory, it will use the same site. Warning: This command will delete the folders static/ and templates/ locally if they exist. Packaging OS X App #!/bin/bash VM_IP= ssh kim@$vm_ip./deploy/make_app.sh scp kim@$vm_ip:deploy/packages/aldryncloud.dmg ~/Desktop/ Workflow: This script calls make_app.sh on the vm, which updates the repo & then calls the deploy.sh from the repo. In the end, the.dmg file gets copied to your local desktop Local Setup You can override the host it s talking to by setting the environment variable ALDRYN_HOST to something (for example: If you want to use the client locally, just invoke it like this: ALDRYN_HOST= aldryn <command> Starting the GUI Application from the Commandline aldryn gui - starts the Aldryn Application 2.3 Addons Addons are the building blocks for your website. An Addon is a re-usable django app with some extra metadata that makes it work on aldryn Packaging and Sourcecode If you want to write an addon, write a standard Django app (including working setup.py!). An addon requires a configuration file named addon.json which follows the general json guidelines. Place this file next to your setup.py and you should be ready to run aldryn addon validate. All addons must have a valid license file. Preferably called LICENSE.txt in the root of the Project. The following is an example of a configuration file using all options: { "name": "My Addon", "description": "This is my custom application.", "version": "1.0", 2.3. Addons 9

14 } "url": " "package-name": "my-addon", "installed-apps": [ "my_addon" ], "author": { "name": "Divio", "url": " } Note: Please follow a strict Versioning Scheme! Options name The name of your boilerplate description A description of your boilerplate version The version of this boilerplate (must be compatible with LooseVersion) url The url to your repository or website -name The package name of your app (the thing you have in setup.py under name) -apps A list of apps that need to be added to INSTALLED_APPS to make your app work. author name: Your name! url: URL to your website (optional) Source Repository Guidelines Use our cookie cutter template for addons: (does not exist yet :-( ) The Source should contain: README.rst A short introduction what the package is about. Installation instructions (non-aldryn, like with any other package) Todo more guidelines. link to someplace where this is well described. 10 Chapter 2. Table of Contents

15 Include a link back to aldryn rst: This package is compatible with Aldryn < _. markdown: This package is compatible with [Aldryn]( LICENSE.txt Todo links/description of common licenses MANIFEST.in include LICENSE.txt include README.rst recursive-include mypackage/templates * recursive-include mypackage/static * recursive-include mypackage/locale * recursive-exclude * *.pyc Addon Configuration If you want to provide configuration (and a nice form) for your app, you may add a file aldryn_config.py to the root of your app (next to setup.py). This configuration form will then be displayed on the detail page of the installed addon on the controlpanel. This file must contain a class named Form which must subclass aldryn_client.forms.baseform. The Form class may contain any number of form fields Addons 11

16 Available fields are: aldryn_client.forms.charfield aldryn_client.forms.checkboxfield aldryn_client.forms.selectfield aldryn_client.forms.numberfield aldryn_client.forms.staticfilefield All fields must provide a label as first argument and take a keyword argument named required to indicate whether this field is required or not. CharFields take optional max_length and min_length arguments. SelectField takes a list of tuples (Django style) as required second argument). NumberField has optional min_value and max_value arguments. StaticFileField takes an optional extensions argument which is a list of valid file extensions. Generating settings To generate settings, define a to_settings method which takes two arguments: A cleaned data of your form A dictionary of existing settings (which contains MIDDLEWARE_CLASSES). Add the settings you want on to the settings dictionary and return it. Custom field validation If you want to have custom field validation, subclass a field and overwrite it s clean method, which takes a single argument (the value to clean) and should return a cleaned value or raise aldryn_client.forms.validationerror with a nice message as to why the validation failed Code Conventions The Aldryn certified Addons all follow a distinct coding style. Some rules are of a more cosmetic nature, others exist to easy interoperability between Addons. Important: PEP8, PEP8, PEP8! But with a max line length of 100 instead of 80. On Aldryn we strive to have a system that is as automated as possible. Whenever possible something should work automatically. If it can t be done automatically we want to assist in the manual process as much as possible. Addon updates should be as automated as possible. Make sure you stay backwards compatible or supply clean upgrade paths. A CHANGELOG.rst is a must. Every release should be listed, the newest being at the top. Backwards incompatible changes must be clearly listed. Preferably with a link to further documentation with help to migrate in such cases. More about packaging 12 Chapter 2. Table of Contents

17 Model Field Naming Date and time: Use the _at suffix for datetime and the _on suffix for dates. timestamps (usually automatically created): created_at, created_on, modified_at, modified_on (past time form!) date/datetime that control something: publish_at, start_at, end_at (use imperative form) item_count (for amounts) Reverse relations: use the default <modelname>_set for ForeignKeys. This avoids a lot of ambiguity and complexity with irregular plural forms. python: use single quotes everywhere. templates: see template readability counts: it does not matter if the resulting html has excess whitespace after indenting loops and ifs Database Fields ForeignKeys that can be blank, should also have on_delete=models.set_null. This prevents cascade deletes of a lot of attached content that is usually not what you want. Filer fields are also ForeignKeys, so the rule above applies! Injecting HTML Add-ons can use special APIs to inject content into templates (either in the head or at the end of the body) from Python. This is done by by the aldryn-snake app. It is pre-installed in all aldryn sites and all templates render these sections by convention. Those APIs are: aldryn_snake.template_api.registry.add_to_head to add content to the head. aldryn_snake.template_api.registry.add_to_tail to add content to the end of the body. If you re using those APIs, you probably want to do so from a models.py file (so they are registered at import time). 2.4 Boilerplates Boilerplates are a set of default templates and staticfiles. A boilerplate will typically define how the django templates are structured and make opinionated choices about what javascript frameworks to use and what css tools (SASS/LESS) are used. Typically you don t need to create your own boilerplate, just use one of the existing ones Boilerplates 13

18 2.4.1 First Steps Boilerplates are a set of default templates and staticfiles. The structure will be something like: /private/ for files like less, sass or haml (this folder is not publicly accessible) /static/ for static files like images, stylesheets and javascript /templates/ for all required templates including the starting base.html boilerplate.json the configuration file described in boilerplate.json A full example can be found on Templates Django sets the standard template to templates/base.html. So we will start our Hello World example within this files. But before we write any code, we need to clarify some concepts Aldryn uses. First of all, there are two important libraries for managing media and snippet insertions: django-sekizai aldryn-snake django-sekizai requires {% render_block css %} and {% render_block js %} to be inserted within your base.html. The css block needs to be added within the <head> section of your document. The js block can bee added either within the <head> or <body> section. However we recommend adding it just before the </body> tag so your site loads first everything else before it reaches the javascript part. aldryn-snake adds two very specific tags: {{ ALDRYN_SNAKE.render_head }} and {{ ALDRYN_SNAKE.render_tail }}. These behave similar to django-sekizai, except they can also render entire html snippets or code. render_head should be added before the closing </head> section and render_tail just before the closing </body> tag. In addition, we need to implement the django-cms specific tags. Add {% load cms_tags %} as the very first line within your base.html and than include {% cms_toolbar %} just after your <body> tag. Now we include some basic markup into base.html and the result should be similar to: {% load cms_tags %} <!doctype html> <html> <head> <meta charset="utf-8" /> <title>hello World</title> {% render_block "css" %} {{ ALDRYN_SNAKE.render_head }} </head> <body> {% cms_toolbar %} <p>hello World</p> {% render_block "js" %} {{ ALDRYN_SNAKE.render_tail }} </body> </html> 14 Chapter 2. Table of Contents

19 Hint: Within the divio-boilerplate we use base_root.html to define this setup and base.html extends base_root.html. This is a perfect example of how djangos template inheritance works and you might want to check more possibilities within the django template documentation. Static Files This folder is completely accessible to the public. You can access files by combining your websites URL and the folder /static/. You would end up with something like The structure there can be freely arranged as you please. For the divio-boilerplate we choose shorthands like js, css, img. You can also place your fonts, favicons and much more into /static/. We recommend adding only layout specific files. Images for galleries or downloadable files should be managed using the django-filer which can be accessed through the admin. You can link within your templates to your static files using django s {% static "" %} template tag. For this to work, you need to add {% load static %} first and than reference to your file, for example: {% static "img/logo.png" %}. You can ommit /static/ as the template tag will automatically append the correct path. This is helpfull if you are using CDN s. So we recommend to always use this tag within your templates or snippets. Private Files Private files are not accessible to the public and are mostly used for preprocessors like less, sass or haml. To get started, create a folder with the containing files like /private/sass/ and add required configuration files within /private/. Aldryn will than automatically detect your settings and convert them into our system. Configuration files can be set to compile locally. Within the divio-boilerplate example, base.scss will be compiled into /static/css/base.css. You can also have multiple preprocessors so you would end up with a structure like: /private/ - coffeescript/ - haml/ - sass/ Warning: Aldryn currently only supports sass / compass. Additional services like less, haml or coffeescript will be added soon. Boilerplate.json Add a boilerplate.json configuration file so Aldryn can recognise your boilerplate, validate and upload it to the market place. This file is described in more detail within the configuration section. Upload As soon as everything is ready, you will have to upload the boilerplate to Aldryn. This requires the aldryn client which will provide you with the following two commands for boilerplates: aldryn boilerplate validate aldryn boilerplate upload 2.4. Boilerplates 15

20 The first will validate your configuration file (boilerplate.json) and the second will upload your boilerplate to the marketplace. In short: 1. Navigate to the root folder of your boilerplate using any Shell that is available to you 2. Ensure you are logged in to the aldryn_client running aldryn login 3. Validate the boilerplate running aldryn boilerplate validate 4. Upload the boilerplate running aldryn boilerplate upload Now you can navigate to the my boilerplates and install your boilerplate. Warning: All boilerplates are currently set to be private. As a result, only yourself and shared users can install or modify the boilerplate. We will cahnge this setting in the future so you can define this state. Hint: You can update a boilerplate by increasing the version within the boilerplate.json. To upload follow the Upload steps again Configuration A boilerplate requires a configuration file named boilerplate.json which follows the general json guidelines. This file is placed within the root/ of your boilerplate and can be validated using the aldryn clients command aldryn boilerplate validate. The following is an example of a configuration file using all options: { } "name": "My Boilerplate", "description": "Uses default resets and stylings.", "version": "1.0", "url": " "templates": [ ["fullwidth.html", "full width"], ["sidebar_left.html", "sidebar left"], ["sidebar_right.html", "sidebar right"] ], "protected": [ "templates/base.html", ], "author": { "name": "Divio", "url": " } Note: Please follow a strict Versioning Scheme! 16 Chapter 2. Table of Contents

21 Options name The name of your boilerplate description A description of your boilerplate version The version of this boilerplate (must be compatible with LooseVersion) url The url to your repository or website templates A list of tuples in the form of (template_path, verbose_name). The template_path is the path to the template as used by Django. The verbose name is what users will see. protected A list of files that are protected. Protected files will be upgraded when a user upgrades the boilerplate and has not changed the file since the last upgrade. author name: Your name! url: URL to your website (optional) Protected Files Protected files have an additional lock status which is visually represented on the aldryn.com online editor. This status represents, that these files should not be modified in any way. This could apply to libraries such as normalize.css or jquery.min.js An example of a configuration showing only the protected block:... "protected": [ "templates/base.html", "static/js/jquery.min.html", "static/css/normalize.css", ] Initial Data Warning: This feature is still in development and might be temporary unavailable. To include initial data in your boilerplate, add aldryn_client to your installed apps in your project and call the management command aldryn_dumpdata <outfile> <language>. <outfile> must be a file named data.json located next to your boilerplate.json file. <language> is the language code of the language you want to include ( en is a good default choice). Only one language can be included Boilerplates 17

22 Handling relations in plugins If your plugins include relationships to other models that need to be included, define a setting ALDRYN_DUMPDATA_FOLLOW which is a list of strings in the form of PluginName.relationship_field Code Conventions There are many boilerplates and equally as many code conventions and styleguides. We will not go as far as to command you to use tabs over spaces, camcelcase over under_score, but we might want you to redirect to our aldrynboilerplate s README.rst which offers some advice. When it all comes down, you can use whatever coding style you wish. There are though, some restrictions concerning the folder structure: /private/ /static/ /templates/ These folders are all required. private You can place preprocessors within the private folder, such as sass, less or coffeescript. These will automatically compile to your specified destination. In case of sass, configuration is defined within config.rb. This folder cannot be access over http. static You can place almost any layout specific file here: css, javascript, fonts, cat pictures and even folders. This folder can be accessed ofer http. templates Django is per default always looking for a base.html file located within /templates/. This is the starting point for your html structure and design. This folder cannot be access over http. 2.5 Themes First steps This is a rough overview of how to create and implement a theme: 1. Create a base theme project similar to 2. Add aldryn-snake and aldryn-theme-standardsite to your installed apps before any other apps that use templates or static files for local testing 18 Chapter 2. Table of Contents

23 3. Create essential symlinks to make templates recocnisable on your local setup: cd aldryn-theme-standardsite/aldryn_theme_standardsite/templates/ ln -s. aldryn_theme_standardsite 4. Copy and prepare all the files you need: templates, static and private 5. Create symlinks for missing libs within sass or similar if there are shared within your boilerplate: ln -s aldryn-boilerplate/private/sass/libs libs 6. Create and maintain your addon.json When to use a theme? We recommend using a theme only if you use the same design/frontend within multiple sites. This allows you to update the design centrally and apply the change to all your sites. However, it does not make sense to create a theme for a single site/design, as the update process can be done either within the boilerplate alone or manually Configuration A theme requires the same setup as an addon. In addition you will have to declare the assigned boilerplate. For example, aldryn-theme-standardsite requires aldryn-boilerplate, so we assign "theme": "aldryn-boilerplate" at the top to declare it as a theme addon. This is the example for aldryn-theme-standardsite: { } "theme": "aldryn-boilerplate", "name": "Theme Standardsite", "description": "Custom theme", "version": "0.0.1.a", "url": " "package-name": "aldryn-theme-standardsite", "installed-apps": [ "aldryn_theme_standardsite" ], "author": { "name": "Divio AG", "url": " } Inheritance Inheritance is an important factor when creating a theme. If we look at a traditional setup, we would proceed as follows: 1. Create a project 2. Copy essential files (boilerplate) 3. Setup addons (packages) 4. Modify code (frontend) 2.5. Themes 19

24 We quickly lose the opportunity to update code automatically as we change code on almost any place. This can be especially tricky if you have to support a specific frontend setup for multiple sites. In case of aldryn we separate aldready boilerplates and keep them up to date, but what about the design? How it works In short: 1. A boilerplate creates the foundation 2. Addons create the structure but do not modify the foundation 3. A theme creates the look and might modify the structure or foundation After the site is created and a boilerplate is available, you will start adding addons to your site. Addons add additional templates and static files to your setup. Addons do not overwrite existing templates or static files. When adding a theme hovever, we might want to extend the foundation a bit or change the structure slightly. So a theme can control both and overwrite files if required. 2.6 Workflows for Agencies Best practices for Agencies using Aldryn Ownership and sharing Agencies will likely have their own Addons that are developed by multiple developers. We recommend to setup a shared agency account that owns all addons, boilerplates and sites. Then share the addons with all the developers that need access. Sharing sites Sites can be shared from the controlpanel. Select Share Site. Developers and Project Manager will typically need Control panel access. Customers usually only need access to the website and not the control panel. To quickly show the stage site to someone without bothering with logins, the Link to share can be used. Sharing Addons Typically addons will be shared with all Employees of the agency. Developers will need the Can use and update Permission. Project Managers will need the Can only use Permission. Sharing Boilerplates In most cases you will not need to build your own boilerplate. If you do, developers will need full access and project managers read/use access. 20 Chapter 2. Table of Contents

25 2.7 FAQ There are no frequently asked questions yet. 2.8 Glossary Control Panel The main application of Aldryn. It allows adding and managing Sites. Located at Site, Sites A django CMS website deployed from the Control Panel running on the Cloud. Base Project The base project used as a template for Sites. This is not a website, but rather part of the Control Panel. Git repository is at Cloud The infrastructure that host Sites. Addon, Addons A Django application which can be installed to a Site. Addons can be installed to Sites on the Control Panel Login Authentication application used by Control Panel, and Deployed Sites. Located at Git repository is at Boilerplates A set of templates, static files and optionally compass files. Similar to a theme, but Aldryn does not allow changing of boilerplates, which is why they re not named theme FAQ 21

26 22 Chapter 2. Table of Contents

27 Index A Addon, 21 Addons, 21 B Base Project, 21 Boilerplates, 21 C Cloud, 21 command line option installed-apps, 10 package-name, 10 Control Panel, 21 I installed-apps command line option, 10 L Login, 21 P package-name command line option, 10 S Site, 21 Sites, 21 23