Learn from Saki: How to write an example

The idea is to have a single page for each example where the user can find all information of the example. He does not need to click somewhere to run it, click elsewhere to see the source code, and click once again to see the description.

Examples consist of three parts:

Example application
Example page
Download package

Example application

Step 0: See the existing examples

First of all, see how the existing examples are done mainly Styling Grid Rows. Scroll through the example to see what’s there.

Step 1: Generate worspace and application

The application should be generated by Sencha Cmd preferably in a workspace. For that:

cd /devel/ext-4.2.2
sencha generate workspace ../ws
cd ../ws/ext
sencha generate app ExampleSgr ../saki-styling-grid-rows

The code above assumes we work in /devel directory (that is also http server document root) and that Ext download package has been unzipped into ext-4.2.2 subfolder.

The recommended namespace is ExampleXyz, where Xyz is abbreviation of the example name; Sgr stands for Styling Grid Rows in the above code.

Directory name of the application should start with author’s nickname followed by dash delimited example name as is saki-styling-grid-rows above.

Step 2: Initial application setup

It is necessary to switch off autoCreateViewport in the newly generated application as an example is embedded in the page so we cannot take all browser space, what viewport does.
We cannot even render to the body because we want to use the running app inline with the text or running in a window created by clicking on a button – button also inline.

Therefore, we need two things:

a container created in index.html, e.g.:
```
;
```
Note: index.html is needed only for development, we use compiled JavaScript and CSS on the site.

launch method in Application.js that renders to that container:

// create and render the grid view in a container or in the body
Ext.widget('demogrid',{
     renderTo:Ext.fly('example-grid-ct') || Ext.getBody()
    ,title:me.title
});

Step 3: Develop the application

While developing, try to keep the application simplest possible so that it shows only what its name states. I have probably made a mistake of showing more than necessary in Styling Grid Rows example that also includes “How to have multiple instances of a view”, “How to use custom events” and “Basics of SASS”. Don’t do the same mistake, keep it simple.

The application must be well written: easy to read, appropriatly indented and commented, high quality.

I recommend naming of classes like this: PersonModel, PersonStore, PersonGridView, PersonController, i.e. name always contains MVC role in the end.

Compile the app when finished.

Example page

Step 4: Sign-up as Free Member (only first time)

Go to the Free Registration on the site, fill in the form and click the confirm link in the registration mail you receive.

Step 5: Contact me (only first time)

Contact me (Saki) as I have to create an Author account for you so that you can write and publish pages on the site.

Step 6: Create the example page

Login to the site an go to the WordPress Backend. Then click on Pages/Add New in the left menu.
Type the title that says what the example does. WordPress automatically suggests the permalink when you move the caret from the title text box.
Edit the suggested permalink so that it reads example- followed by dash separated example name, e.g.: example-styling-grid-rows
Write the text. The suggested sections are:
- Description
- Live Demo
  
  For Live Demo you need to insert the empty div with same id as you have in you index.html so that the example application can render to this container
- Main Features
- Use Cases
- Example Files
- Source Code
  Source Code visibiliy depends on visitor membership level, but this dependency will be setup by me. You will copy and paste the source code from the application, file-by-file in <pre> tags as follows:
```
<code>Application.js:</code>
<pre class="lang:js range:23-9999 mark:34-38,41-45 decode:true">
// complete source from Application.js here
</pre>
```
  Notes: lang sets the laguage for the code highlighter and it will usually be js, css,sass or xhtml. range says which line numbers to display – I usually strip the file headers therefore 23–9999. mark highlights the specified line ranges with yellow background to draw visitor’s attention to the most important parts of the code.
- Source Code Walkthrough Video (optional)

Step 7: Set page options

You need to set:

Page Templage to Example Page Template
Dynamik Label to Ext Example
Custom field ext_example_css to the path of your css. For example:
/apps/saki-styling-grid-rows/resources/ExampleSgr-all.css
Custom field ext_example_app to the path of your application. For example:
/apps/saki-styling-grid-rows/app.js

Note: Mind that the css and app above are compiled versions as generated by sencha app build

Now you can publish the page.

Step 8: Upload compiled files

Use your ftp client to upload compiled files to the site – contact me for ftp credentials. The directory and file names must match the above css and app.js links.

Download package

Just send me zipped sources of the example application directory – for now I have no automation or author executable steps. I will do the rest so that paying subscribers will be able to download the sources.
I zip with the following bash script, if it helps:

#!/bin/bash
if [ $# -lt 1 ] ; then
    echo "Package name required"
    exit 1
fi

pkg=$1
pkg=${pkg%/}

zip -r ${pkg}.zip $pkg -x \
        "$pkg/guides/*" \
        "*.DS_Store" \
        "$pkg/makedoc.sh" \
        "$pkg/tags.rb" \
        "$pkg/docs.json" \
        "*guides.json" \
        "*examples.json"

Looking forward to your examples.

How to write an example