From Xano Documentation
Jump to: navigation, search

Developer Overview

The Xano platform is composed of many components. This page will serve as a crash course for a quick overview of the entire system. Then once you have an idea of what this platform can offer, you can dive deeper into other technical areas to get a better understanding of how things work.

Core Components

ApplicationContext

The ApplicationContext is your swiss army knife. No matter where you are in source code, you will have access to the ApplicationContext. The ApplicationContext has complete control over everything, so if you need to do something and you have the ApplicationContext, chances are you have all you need to complete that task.

Extensions

Everything in the Xano platform is derived from extensions. The Xano platform itself is composed of 70+ extensions. Although it could easily be one single extension, spreading functionality out across multiple extensions gives you the ability to only use what you really need for whatever task you are trying to accomplish.

Each extension has the ability to depend upon other extensions. Dependencies allow the platform to know if the right extensions are in place to make sure everything is running properly. Also, if you are using the marketplace, it allows you to install other extensions automatically based on the dependencies.

Extensions are responsible for providing support for installation and upgrades. This is usually limited to just database maintenance. A new version of an extension may add a field to a database table, rename a field, change its storage requirements, or add a brand new table to the database.

Any complex extension is responsible for creating a context. See below for more details.

Contexts

Contexts provide the ability to control their extension. This may include something simple like registering some input fields for a form, or more complex tasks like creating a handler to deal with API requests.

A context is created by its extension. Once it is created, it automatically gets registered with the ApplicationContext.

Extension names and Context names are generally the same. This means that if your extension is called "Example", then there is a good chance your context's name is "Example". Retrieving the context is done through the ApplicationContext.

The ApplicationContext has the ability to load other Contexts.

$exampleContext = $app->getContext("example");

If the context hasn't been loaded yet, then the ApplicationContext loads the matching extension and creates it dynamically.

Enhancements

Enhancements are a powerful feature of Xano. Each extension has the ability to enhance other contexts and/or functions. The reason why this is so important, is because these enhancements are non-destructive. That means the original core source code isn't getting modified. If it isn't getting modified, then you never are at risk of going off the beaten path and messing up all future opportunity to receive easy software updates.

Enhancing a context allows extensions to add functionality to another context without it actually knowing about it. A good example of this would be if you wanted to add a new content type. Let's say your Xano instance has objects, videos, and blogs. You wanted to add a new type called product. You could do this by creating a new extension and then enhancing the content extension by registering with it the new product type.

All enhancements are done at context creation time. This means that once you receive the object from the ApplciationContext's getContext function call, all the enhancements have already taken place.

Enhancing a function allows you to intercept the result, perform additional processing on it, and then return it as you were never there. Function enhancements can be chained... meaning that multiple extensions can each enhance the same function. An example of a function enhancement would be the following. Let's imagine there is a function that returns a list of transactions that you recently made. A function enhancement could take that list of transactions, filter our certain ones for whatever reason, and then return the modified result, as if that was the original intention of the function all along.

Frameworks

Data Requirements

The Data Requirement Framework is a new approach to web page development. It consists of the ability to manage all data requirements, assign them to web pages, execute them, and publish there results to a templating engine.

A Data Requirement is an interface to collect data. This interface can be assigned to web pages, which implies that the web pages are interested in the result of the data requirement. Once the web page is run, each of these data requirements get executed, and the result is accessible from within the web page through the templating language. Once you start using these data requirements, you will be amazed at how easy it is to get a 10,000ft view of what your entire web property is doing.

API Queries

The API Query Framework is responsible for managing all API requests for the Xano platform. This framework consists of API queries and a manager.

The Api Query interface provides a way to handle an API request. An API request commonly consists of authentication, input processing, data processing, and output handing. API Queries can be organized via their class namespace.

The framework allows you to identify every entry point into the system, since the one way to make modifications externally is through an API Query. It is then easy to see statistics on each query and identify errors before they become a major issue.

Background Tasks

The Background Task Framework provides an organized way to manage all of Xano's background tasks, monitor each of them as they perform their task processing, and provide insight into if they executed properly.

A Background Task is an interface for creating a task that needs to get executed in the background. Because these tasks run in the background, they are not part of any web page or request. No other part of the application should be waiting for them to complete. Once a task completes, it has the ability to broadcast its result. Although some tasks may be important to finish as quick as possible, they are never time sensitive.

Each task can run on basic intervals or be scheduled via an API Query.

Frontend Components

Sites

Each web property is encapsulated by a Site object. Short for "website", a site is accessible through a domain name. If you have 3 domain names, then chances are you are going to have 3 sites.

A site gives you the ability to configure certain settings like user options, password security, contact information, etc.

Branches

Branches are essentially versioned sites. Each site can consist of multiple branches. Branches include versions of all site related data, such as: settings, pages, layouts, macros, and files.

Branches create the ability for developers to be editing portions of the website that are not being viewed by the standard web visitors. Once the changes are done, a branch can be set to live, which instantly will make the new updates available to everyone.

Like sites, branches have the ability to also have settings. Site settings are global across branches, but branch settings are limited to each branch.

Pages

Pages are what is commonly viewed within a web browser. Each branch consists of a list of pages. Each page can be directly accessed through a URL by referencing its name.

http://example.com/myname is requesting a page named myname.

A page generally consists of HTML, but its content-type can change depending on the application. Other formats include, json, xml, rss, etc.

Pages can be done the standard way where they literally consist of all of the HTML for that page, or they can use the new block structure, which is available through layouts.

Layouts

Layouts are a tool designed for flexible templating. Layouts consist of the standard HTML structure, but also have the ability to name blocks of text. When a page extends a layout, it has the ability to override a block to do something custom for that page.

This functionality allows a lot of flexibility in terms of customization with just a little bit of overhead by properly naming the important blocks in the base layout.

Example Layout - base.layout
<html>
  <head>
    <title>{% block title %}My Website{% endblock %}</title>
    <meta name="keywords" content="{% block keywords %}{% endblock %}" />
    <meta name="description" content="{% block description %}{% endblock %}" />
  </head>
  <body>
    {% block content %}{% endblock %}
  </body>
</html>
Example Page using base.layout
{% extends "base.layout" %}

{% block title %}Shopping Cart{% endblock %}
{% block description %}Add as many products to your shopping cart and get them delivered the very next day!{% endblock %}
{% block keywords %}Shopping Cart, Products, Next Day Shipping{% endblock %}
{% block content %}
  <p>Welcome to my store</p>
  <p>Here are a list of products that you can purchase: water bottle, workout gloves, backpacks, etc.</p>
{% endblock %}
Output from template engine
<html>
  <head>
    <title>Shopping Cart</title>
    <meta name="keywords" content="Add as many products to your shopping cart and get them delivered the very next day!" />
    <meta name="description" content="Shopping Cart, Products, Next Day Shipping" />
  </head>
  <body>
    <p>Welcome to my store</p>
    <p>Here are a list of products that you can purchase: water bottle, workout gloves, backpacks, etc.</p>
  </body>
</html>

Macros

Macros provide the ability to reuse code. Macros can be defined once and called multiple times to do repetitive tasks throughout the site.

Macros have no way of returning a result. Their intended use is to print data out to the screen. Therefore a macro would be something that formats an HTML table... not a something that performs complex math calculations.

Example macro
{% macro formatDate(myDate) %}
  <p>The date is: {{ date(myDate)|date('m/d/Y') }}</p>
{% endmacro %}
Template Code
{{ formatDate('now') }}
{{ formatDate('yesterday') }}
{{ formatDate('+2days') }}
Output
<p>The date is: 1/20/2014</p>
<p>The date is: 1/19/2014</p>
<p>The date is: 1/22/2014</p>
Scope

It is important to mention that macros are completely isolated from other variables. If a macro needs access to certain data, then it needs to be passed in as a parameter. There is one exception - template globals are always accessible.

Rewrites

Rewrites allow you to create SEO (Search Engine Optimized) friendly URLs. This is done by partitioning the URL namespace and assigning portions of it to URL variables.

Non-friendly SEO URL
http://example.com/?page=video&contentId=NewMovieTrailer10
SEO Friendly URL
http://example.com/video/NewMovieTrailer10

With the SEO friendly URL, the rewrite is doing pattern matching and then assigning video to the page and NewMovieTrailer10 to the contentId variable. All of this is being done behind the scenes.

Files

File support allows the ability to upload and serve files through the website. This is limited to site specific - static content only... not user generated content.

There are several hook mechanisms that allow for additional on the fly processing of these files. Some examples include the ability to resize images on the fly, as well as compile javascript and css files into minified and obfuscated code.

Template Engine

Xano leverages a very powerful template engine. This engine includes a flexible templating language, tight integration with the Xano platform (eg. pages, layouts, macros, modules, and even files), and a renderer which can process templates and output a finished result.

A templating language provides a clear separation between your frontend and backend application layers. This means you can safely make changes to your HTML, Javascript, and CSS files without the worry of having to tiptoe around any complex backend source code. This becomes extremely important when the size of your team grows and you have multiple people working on the same project. Keeping layers isolated from each other, while still providing flexibility is critical to product stability as well as effectiveness of the individuals doing the edits. For example, a designer making a quite template modification shouldn't have to dig through PHP source code.

For more detailed information visit the Template Engine documentation.

System Management

Content

The Xano platform comes integrated with content management. Content management gives you the ability to add new content, edit existing content, browse through portions of it with filtering, sorting, and ordering options, and run reports on it.

Each content object contains a type. This type field allows partitioning to take place between different types of content. Some sample types include blogs, videos, photo sets, projects, products, etc. It is very easy to extend the content management system to support new types that are applicable to your project.

This service comes stocked with data requirements to pick and choose for your web pages. Each of these data requirements provide different views of your content, which can be readily accessed in your template code. API queries are also provided for different ways to add, edit, and delete your content.

The Administration panel comes stocked with pre-built workflows to handle your content management needs.

Users

The Xano platform comes integrated with user management. Like the content management server, user management also provides the ability to add, edit, delete, and browse users. However, there is additional support for securing signing up a users, performing authentication, logging a user in, logging them out, forgot password workflows, etc.

All of these additional features are provided through the API Query framework. It is easy to customize these queries to your specific application, or create new queries for completely different functionality.

The Administration panel comes stocked with pre-built workflows to handle your user management needs.

Software Releases

The Xano platform comes integrated with software release management. This includes support to create software builds, keep track of the previous software builds, and deploy software builds.

Each build is responsible for loading in all the extensions, packaging them out, collapsing them together, and then producing a finished product. Because of the flexibility of the extension framework, it is easy to add support for multiple source code repositories. This can be extremely beneficial for legal reasons, where you want to guarantee certain source code is never co-mingled with other source code. This is comes in handy for organizational purposes with multiple teams, where each team is responsible for their own repository. The platform supports unlimited repositories, so you can get as creative as you want with your software development process.

Servers

The Xano platform comes integrated with server management. Most applications tend to start on a single server, but can quickly turn into larger projects that need to be distributed across multiple servers.

Server management starts to become extremely useful when packaged together with the software release management service. When using multiple servers, it is important to keep track of which build is deployed to which server and make sure to catch any differences before they turn into a larger problem.

Load Balancing

The server management service lays the groundwork for the load balancing service. This can be complex subject, but Xano does its best to simplify it. Load balancing comes in many different flavors listed below:

Extensions

Extension load balancing provides a method for specifying certain extensions to only be enabled on specific servers.

For example, if you had a encoding extension that consisted of a background task, you could have it so it would only run that background task on the servers you specified to enable that extension.

Another example would be an image serving handler. This handler would handle web requests for images, perform some optional image transformations, and then respond with the result. Depending on your application's web traffic load, this could become very resource intensive. By leveraging the extension framework, this can easily be spread out across multiple servers. This type of load balancing is commonly coupled with DNS or hardware HTTP load balancing.

DNS

DNS is a service where a hostname translates into an IP address. For example, www.example.com is a hostname, and depending on its DNS settings, it may be setup so it connects to a server at IP address 127.0.0.1.

DNS load balancing is where your application's DNS service spreads the web traffic load across different servers by picking which IP address to use from a pool of IP addresses at each hostname resolution. A round robin approach is common for DNS load balancing. In this scenario, lets say we had 3 different servers with the IP address of 127.0.0.1, 127.0.0.2, and 127.0.0.3. If you went to the website at the hostname www.example.com, then each time you refreshed your browser, you would potentially have a 33% chance of having one of those IP addresses.

Xano supports the ability to specify top level hostnames for its application, which provides support for DNS load balancing.

Hardware

Hardware load balancing is similar to DNS load balancing, except the hardware device handles the request routing on its own. You could think of this as DNS load balancing within the internal network.

Hardware devices allow much greater flexibility upon detecting server failures and dynamically re-routing requests. But it comes at an expensive financial and time cost to purchase/rent, setup, and maintain.

Xano supports the ability to specify top level hostnames for its application, which provides support for hardware load balancing.

Database

Database load balancing consists of maintaining multiple copies of the database in what are commonly referred to as "read replicas". If your database server supports 250 connections per second, then if you add 3 read replicas, you can now easily scale up to 1000 connections per second.

The only drawback to this, is that modifications to the database can sometimes result in delayed propagation to the read replicas. Because of this, certain requests may need to only routed to the master database.

Xano supports the ability to reference read replicas, as well as optionally connect directly to the master database. This allows support for database load balancing.

Data Sharding

Data sharding is a form of load balancing, by spreading data across multiple servers. When a web request is received, it figures out the location of the data and then goes to the particular server "shard". This is a common approach for extremely large enterprise applications spanned across tens, hundreds, and even thousands of servers.

This approach can be applied to data storage or databases.

The Xano platform comes integrated with this for blob storage. Database sharding is much more complex and usually needs expert advice that tends to be application specific. For those interested in database sharding, please contact the xano support team at support@xano.com.

Blobs

The Xano platform comes integrated with blob management. Blobs are defined as large binary objects, however they technically don't need to be large. The idea behind it is that your application should be lightweight with metadata stored in your database and then your database should reference blobs stored in separate storage. For example, a video title would be stored in the database, but the actual video would be stored as a blob.

Combined with server management support, the Xano platform has the ability to spread blobs across multiple servers. Blob storage can done in several configurations, where it fills up a server and then moves on the next one, or it could be spread out evenly over a cluster of servers.

No matter which way you choose, blob storage makes things easy and efficient for storing large objects.

Misc

Class Auto-Loader

The Xano platform relies heavily on class auto-loading. This feature allows you to reference each of your classes without having to worry about loading their files manually.

Relying on namespaces provides the ability to use directories for organizational purposes.

Example Xano Installation Directory

Let's assume that the xano platform is installed in the following directory.

/projects/myxanoproject
Source Code directory for auto-loading of classes
/projects/myxanoproject/includes
Sample Class
<?php

  namespace xano\misc;

  class RandomNumber {
    static function generate() {
      return mt_rand();
    }
  }

Sample Class File Location
/projects/myxanoproject/includes/xano/misc/RandomNumber.php

Normally if you wanted to use the xano\misc\RandomNumber class, you would have to include it at the top of each file wanting to use it. Because of the class auto-loader, whenever this class is referenced, it automatically gets included based on its namespace and class name. The namespace and class name get directly mapped to a file within the source code class directory.

File/Directory Structure

The Xano platform relies upon files being in their appropriate location. Below is a list of important files and directories.

Root Directory

The root directory contains everything related to the Xano platform. This directory can be located wherever you want on your server. For this demonstration we are using "/projects/myproject".

/projects/myproject
Application Directory

The application directory includes everything related to the current build of the application. This directory and all sub-directories should be considered READ ONLY. No user generated content should ever be stored in this directory, because it gets completely replaced when a new build is deployed.

/projects/myproject/bin
Storage Directory

The storage directory includes anything from permanent storage for data or temporary storage for log files, etc. This directory has many sub-directories for different extensions.

/projects/myproject/storage
License File

The license file includes important information about your application. Critical settings and configurations are stored within this file. This file gets created upon installation and updated after modifications to your license.

/projects/myproject/storage/license.config
Temporary Storage

This directory includes temporary storage for files. If this directory got completely deleted, the application should still be able to run... meaning that no files in this directory are dependent upon the execution of any source code.

/projects/myproject/storage/tmp
Builds Directory

The builds directory includes storage for all of the application builds created with the Xano platform. Each one of these builds can be deployed through the Xano admin panel. This directory is located within the storage directory, but can optionally be configured elsewhere.

/projects/myproject/storage/builds
Source Directory

The source directory includes temporary storage for files as the packager is creating a build. During each build, this directory gets cleared and then replaced with build specific files. This directory is located within the storage directory, but can optionally be configured elsewhere.

/projects/myproject/storage/src
Repository Directory

The repository directory includes temporary storage for that belong to a particular source code repository. A common repository used within the xano platform is a "git" repository. If your project is relying on git repositories, then this directory would contain relavent versions of the entire repository. This directory is located within the storage directory, but can optionally be configured elsewhere.

/projects/myproject/storage/repo
Blob Directory

The blob directory includes permanent storage for blobs of data (binary large objects). This files stored within this directory commonly include images, videos, attachments, etc. Blob storage can be partitioned across multiple servers, so depending upon your configuration, different servers may be responsible for different blobs.

/projects/myproject/storage/blob
Web Accessible Directory

This directory is completely public. All files located within this directory are web accessible.

/projects/myproject/bin/htdocs
Auto-Loaded Source Code Directory

This directory includes all source code that can be automatically loaded with the class auto-loader.

/projects/myproject/bin/includes
3rd Party Directory

This directory includes 3rd party libraries. Not all 3rd party files are guaranteed to reside in this directory, but the majority of non-public facing 3rd party count should be located here.

/projects/myproject/bin/3rdparty

New technology to bridge the gap between simplicity and flexibility.