Creating a Package

The goal of this tutorial will be to take something that extends Umbraco and create it as a package. The tutorials starting point will be creating a package out of the dashboard from the Creating a Custom Dashboard tutorial. The process will be the same for most packages so feel free to follow along with something else.

Creating a package in the backoffice

If you have something you want to make into a package, you can do so through the Umbraco backoffice.

First go to the Packages section and select Created in the top right corner. Next, choose the Create package button.

On the Create package page there are 4 sections with different info to fill out. Some of the info is mandatory, most of it is not. First of all you should give the package a name at the top - we will call our dashboard the same as in the tutorial: Custom Welcome Dashboard.

The Package Properties section

This section contains mostly meta data about the package and the creator. We will fill in the following things:

The Package Content section

This section is used to determine which things the package should contain. We will fill in the following things:

The Package Files section

In this section you will be able to select all of your own custom files. We will start with the Path to file option.

Since everything in our Dashboard is from the same folder in App_Plugins, we can select the folder and it will include all items inside that folder:

We will leave the Package options view selector empty, but in case you were wondering you can select an HTML file here that will show up as package options. Here is an example from the package Articulate:

The Package Actions section

Here you can add package actions. There are a number of default package actions and you can also create your own custom package actions

Finally after filling out all the info we can select Create to create the package. We will download it, in order to take a closer look at what it contains in the generated zip file.

Inspecting a package zip

When you download and then open the zip package you will find that it looks like this:

The 5 highlighted files were the ones the package contained that we created in the Creating a Custom Dashboard tutorial, however there is another file here called package.xml - so let's take a look at that - it looks like this:

<?xml version="1.0" encoding="utf-8"?>
<umbPackage>
  <files>
    <file>
      <guid>customwelcomedashboard.controller.js</guid>
      <orgPath>~/App_Plugins/CustomWelcomeDashboard</orgPath>
      <orgName>customwelcomedashboard.controller.js</orgName>
    </file>
    <file>
      <guid>customwelcomedashboard.css</guid>
      <orgPath>~/App_Plugins/CustomWelcomeDashboard</orgPath>
      <orgName>customwelcomedashboard.css</orgName>
    </file>
    <file>
      <guid>package.manifest</guid>
      <orgPath>~/App_Plugins/CustomWelcomeDashboard</orgPath>
      <orgName>package.manifest</orgName>
    </file>
    <file>
      <guid>WelcomeDashboard.html</guid>
      <orgPath>~/App_Plugins/CustomWelcomeDashboard</orgPath>
      <orgName>WelcomeDashboard.html</orgName>
    </file>
    <file>
      <guid>en-US.xml</guid>
      <orgPath>~/App_Plugins/CustomWelcomeDashboard/lang</orgPath>
      <orgName>en-US.xml</orgName>
    </file>
  </files>
  <info>
    <package>
      <name>Custom Welcome Dashboard</name>
      <version>1.0.0</version>
      <iconUrl></iconUrl>
      <license url="http://opensource.org/licenses/MIT">MIT License</license>
      <url>https://github.com/umbraco/customwelcomedashboard</url>
      <requirements type="Strict">
        <major>8</major>
        <minor>2</minor>
        <patch>0</patch>
      </requirements>
    </package>
    <author>
      <name>Jesper Mayntzhusen</name>
      <website>https://jesper.com</website>
    </author>
    <contributors></contributors>
    <readme><![CDATA[This will add a dashboard to your content section. 

The dashboard will show each user the most recent nodes they have saved.]]></readme>
  </info>
  <DocumentTypes />
  <Templates />
  <Stylesheets />
  <Macros />
  <DictionaryItems />
  <Languages />
  <DataTypes />
  <Actions />
</umbPackage>

You will notice that each of the fields we created is inside this XML file. All files have an orgPath attached to it - this is where it will try to move the file to when installing it. So, don't worry if you organized your package in folders and they are not so in the zip.