admin/ayanova7
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Browse Source
This commit is contained in:
John Cardinal
2018-06-29 19:47:36 +00:00
commit be7f501333
3769 changed files with 1425961 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

361
doc/Content/AyaScript for AyaNova plugin.aml Normal file
View File

@@ -0,0 +1,361 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="572b9fe6-e499-4cae-a144-3048b6849667" revisionNumber="1">
<developerConceptualDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>AyaScript is a useful utility for testing and running snippets of C# code against the AyaNova developers API</para>
</introduction>
<!-- start header -->
<section><!--H1-->
<title><mediaLink><image xlink:href="AyaNova_Service_Management_Software_Logo" /></mediaLink>
AyaScript for AyaNova</title>
<content><!-- end header --><!-- start page -->
<!-- start content -->
</content>
</section>
<section><!--H2-->
<title>Harness the power of the AyaNova API from within AyaNova!</title>
<content>
<para>Create and execute c# code directly from the AyaNova plugin menu. </para>
</content>
</section>
<section><!--H3-->
<title>About AyaScript </title>
<content><mediaLink><image xlink:href="Script128" /></mediaLink>
<para>AyaScript provides an editor and runtime environment to develop and execute
your own c# code using the AyaNova API and any other resources of the .net
framework.</para>
<para>The cool thing about AyaScript is it's quick, easy and everything is provided
to build and execute your code without requiring any other programs or utilities
such as a development environment.</para>
<para>Scripts are available from within the AyaNova AyaScript plugin menu from
anywhere in AyaNova that you specify.</para>
<para>This means you can quickly create useful utilities or Add-on's without having
to build a full AyaNova plugin or stand alone application and your end users can
execute the script from within the AyaNova program without any programming
knowledge.</para>
<para>Example scripts are provided to get you started</para>
<para>AyaScript is also useful for AyaNova support to provide end users with
snippets of code to resolve unique problems in a timely manner</para>
<para>Since AyaScript code is standard c# code any code developed in AyaScript can
easily be turned into a separate AyaNova plugin or stand alone program that uses
the AyaNova API</para>
</content>
</section>
<section><!--H3-->
<title>How it works </title>
<content>
<para>Scripts are written in standard c# code and have access to the full AyaNova
API and AyaNova business object or list of objects that a user selects in
AyaNova.</para>
<para>When a script is selected to execute by the end user the relevant objects
from the AyaNova application are passed to the script and it's compiled and an
assembly is generated and executed on the fly.</para>
<para>Generated assemblies are cached so there is no performance penalty for
scripts that are executed repeatedly.</para>
<para>Scripts are plain text and everything required to run them is stored in one
text "file" so you can easily move them and share them with others.</para>
<para>All scripts are stored in an xml file (AyaScripts.xml) in the AyaScript
plugin folder in the AyaNova program files folder. You do not need to work
directly with this file as the AyaScript Editor handles all script persistence
and all information required for a script to execute is stored in the text of
the script itself.</para>
</content>
</section>
<section><!--H3-->
<title>Dangers and Limitations </title>
<content>
<para>AyaScript supports c# only, other development languages are not
supported.</para>
<para>Users will need to be experienced in .net development to use AyaScript</para>
<para>We do not provide support for development questions, however we will answer
questions regarding the AyaNova API itself. In other words we can not teach you
how to program but we will be happy to answer questions about using the AyaNova
API on the development support forum.</para>
<para><legacyBold>AyaScript is potentially dangerous</legacyBold> - it allows you to do anything you
can do in the AyaNova program but a million times more quickly so it's very easy
to damage your data. <legacyBold>There is no safety net.</legacyBold> For this reason we recommend
in the strongest possible terms that you develop your scripts on a trial
database or a copy of your live data and test thoroughly before you even
consider making the script available to your live data users</para>
</content>
</section>
<section><!--H3-->
<title>Getting started </title>
<content>
<para>Setup a safe environment to test development: Use a copy of your database or
download an install the trial version of AyaNova</para>
<para>We recommend doing development work in a virtual machine. In fact all AyaNova
development we do here is within virtual machines, there are many benefits to
doing so. We use VMWare Workstation for our own developers however we have also
tried the free Virtual Box utility and it is sufficient for AyaNova development
though not as fast in our experience. Developing in a virtual machine means you
can safely isolate your testing and development from your live AyaNova and a
virtual machine can be easily backed up and transported between hardware
platforms if your computer should "crater" meaning little or no down time.</para>
<para>Once you have a safe development environment set up, download and install the
free AyaScript plugin from the AyaNova plugin's page.</para>
<para>Run AyaNova and select the AyaScript plugin, you will see several sample
scripts. To view the code for them select the first option which is always the
AyaScript Editor. Select Script-&gt;Open and choose the script you want to see
the source code for.</para>
</content>
</section>
<section><!--H3-->
<title>Script HEADER section format </title>
<content>
<para>AyaScripts consist of two sections, the header and main body.</para>
<para><legacyBold>Header</legacyBold> - The header contains c# single line style comments that are
instructions to the AyaScript processor telling it when and where to show the
script menu option to the end user and also the name of the script to display in
the menu.</para>
<para>The header section is *required*, if any part of it is missing or malformed
or doesn't pass a "sanity" check your script will not run or will not be
available. Use the Header builder tool to ensure your script is compliant</para>
<para>AyaScript editor comes with a Header builder tool to automate the process of
setting up the header section correctly, you can use the header builder at any
time to create or edit the header or once you become more familiar with the
header format you can simply type in the options. The header builder is
available from the Edit-&gt;Header menu option in AyaScript.</para>
<para>Note that the header builder displays all possible object types in AyaNova
defined in the RootObjectTypes enumerator in the AyaNova business object
library; at present not all types listed are supported from the plugin menu as
there is either no editor for them in the AyaNova program or they are not an
editable type. However all the main Root object types in AyaNova that your users
are generally concerned with are supported. We've provided all of them as we may
add editors for other types in future through a future update to the AyaNova
program itself.</para>
<para>Header line: <legacyBold>//Script created:</legacyBold> - This is not a required line, it's
simply a convenience that is added by the header builder when a new script is
created, you can delete it if you don't want it there.</para>
<para>Header line: <legacyBold>//Name:</legacyBold> - This is required. When a new script is created
using the new script command it's set to the current date and time however you
can edit it to whatever you want. This is the text displayed to the end user in
the AyaScript-&gt;scripts list. Ideally it should be unique but AyaScript won't
explode if you accidentally name two the same as internally it generates a
unique Guid for each script when they are loaded and uses that instead of the
name.</para>
<para>Header line: <legacyBold>//ShowInMenuFor:</legacyBold> - This is required. This controls in
what situations AyaScript will offer the script to the end user in the menu.
Your choices are Everywhere, Main menu only, Single AyaNova object, List of
AyaNova objects</para>
<para>
<list class="bullet"><legacyUnderline>Show in menu for</legacyUnderline>
<listItem>Everywhere</listItem>
<para>Show regardless of where the AyaNova user is in the AyaNova user interface.
Generally this would be for utilities that are not tied to a specific business
object, for example our Screenshot script, however the list or single object
*is* passed to the script so this could also be for scripts that are designed
to work with any object.</para>
<listItem>Main menu only</listItem>
<para>Only show from the main menu plugin menu item. This is generally used for
utilities that are not designed to work with a specific business object and
indeed when a script is called from the main menu no object is passed to the
script since there isn't one and the object type is set to nothing.</para>
<listItem>Single AyaNova object</listItem>
<para>Only show from the single object editing form and only for the object types
specified in the //HandlesAyaNovaTypes: (detailed below). For example you may
want a script to only be available when in the client entry form or the work
order entry form. This option specifically excludes offering the script in the
menu when the user is viewing a list of AyaNova objects in the user
interface.</para>
<listItem>List of AyaNova objects</listItem>
<para>Only offer the script in the AyaScript plugin menu when the user is viewing
a list of AyaNova objects (i.e. the main form right window). For example if
the user selects clients (or units or vendors or workorders etc etc) in the
left side navigation window and a list of clients is displayed in the right
pane. Note that when a script is selected from a list like this, the ID list
contains only the objects <legacyBold>selected</legacyBold> by the end user so if a user want's
to apply your script to objects in the list they need to select them first.
That being said the underlying list object *is* passed to the script so you
can iterate all the items in the list yourself if none are selected and in
fact many of our plugins work that way on the assumption that if a user hasn't
specficially selected one or more objects then their intention is to apply the
plugin to *all* the objects in the list.</para></list>
<para></para>
<para>Header line: <legacyBold>//HandlesAyaNovaTypes: </legacyBold>- This is required. This controls
which object types you want your script to be shown for. This is the text of the
RootObjectTypes enumeration in the AyaNova API. Use the script header builder to
easily choose the root object types you want to support and ensure they are
spelled correctly. Your script can handle more than one type however if it does
you will need to check the type of the object passed and cast it accordingly.
Generics can be helpful here though scripts are so quick and easy you might find
it easier to simply copy and paste your script and change accordingly for the
different object types. For example if you have a script to process a Client and
want to do the same with a HeadOffice it might be simpler and quicker to simply
copy the script and change the object types in it rather than adding a switch
statement and replicating the same code in one script. Note as stated earlier:
*all* AyaNova RootObjectTypes are listed however not all are suppored by the
AyaNova plugin system. Some are not real objects edited by the end user and some
just don't have an interface for editing alone, however we've left all in
because future updates of AyaNova may contain support for more objects. The easy
way to tell if an object you want to work with is supported is simply run
AyaNova go the the form where you can edit or view that object and see if the
plugin menu option is displayed in the menu at the top. If it is, that object
type is supported and you can work with it in your script. At present pretty
much every object of any consequence is supported.</para></para></content>
</section>
<section><!--H3-->
<title>Script main body section format </title>
<content>
<para><legacyBold>Body</legacyBold> - The body of scripts consists of standard c# code. There is one
required method (AyaScriptMain) and the rest is up to you. You can add other
methods, other classes, includes etc as long as you include the required
AyaScriptMain method. Think of the AyaScriptMain method as the equivalent of a
Main method in a c# console application. It's the method that AyaScript expects
to be there and calls with set parameters. </para>
<para><legacyBold>Comments / Includes / stuff at the top</legacyBold> - You can specify anything you
want above the AyaScriptMain method. Remember this is standard c# so you can use
multiline style comments /*comment*/ or single line comments //. You can also
use include statements to save typing. Note that AyaScript automatically inserts
include statements for you just before compiling the code, this is provided as a
convenience, however if you specify the same include AyaScript is smart enough
to know not to add it again and won't. The automatically inserted includes are:
<list class="bullet">
<listItem>System.Collections.Generic</listItem>
<listItem>System.Data</listItem>
<listItem>System.Drawing</listItem>(Note: System.Drawing.Region conflicts with the AyaNova
business object Region so you must fully qualify like this:
GZTW.AyaNova.BLL.Region)
<listItem>System.Text</listItem>
<listItem>System.Windows.Forms</listItem>
<listItem>GZTW.AyaNova.BLL</listItem>
<listItem>AyaNova.PlugIn.AyaScript</listItem>(Used for predefined forms we may add from
time to time. Initially there is one CopyableMessageBox form included see the
sample for details) </list>
<para></para>
<para><legacyBold>AyaScriptMain</legacyBold> - The main entry point for your script. Required to be
present with the exact method signature and parameters like this: </para>
<code language="C#">public static void AyaScriptMain(bool IsList, RootObjectTypes objectType, Object ayaNovaObject, List objectIDList)
{
MessageBox.Show("Hello from AyaScript!");
} </code>
<definitionTable>
<definedTerm>IsList</definedTerm>
<definition>Will be true if script was called from a list form.</definition>
<definedTerm>objectType</definedTerm>
<definition>AyaNova RootObjectType of passed ayaNovaObject or the type of object in the
list if it's a list object</definition>
<definedTerm>ayaNovaObject</definedTerm>
<definition>If a single object then this is the AyaNova business object, if a list then
this is the list object, if called from the main menu where there is no object
this is DBNull.Value. Note: this is never simply "null".</definition>
<definedTerm>objectIDList</definedTerm>
<definition>If a list, this contains the id's of the AyaNova objects which the end user
has *selected* in the list, otherwise it's an empty list. If IsList is true
and this list is empty it means the user selected your script from a list but
hasn't selected any items in the list. You can either warn them about this or
treat it as an intention to apply your script to all objects in the list in
which case you can get access to the entire list through the ayaNovaObject
parameter which will be the underlying list object itself.</definition>
</definitionTable>
</para>
</content>
</section>
<section><!--H3-->
<title>Support / API documentation / Share scripts </title>
<content>
<para><legacyBold>Support</legacyBold> - As stated previously, while we cannot teach you how to
program we are happy to provide help with specific problems using the AyaNova
API itself. Post your questions to the <externalLink>
<linkText>AyaNova Development / SDK / API section</linkText>
<linkUri>http://forum.ayanova.com/forumdisplay.php?42-Development-SDK-API</linkUri>
</externalLink> of the AyaNova support forum. </para>
<para><legacyBold>Share your scripts</legacyBold> - If you've come up with a handy script you'd like
to share with others copy and paste it into a post in the development area of
our support forum. As we get more samples we'll likely open up a specific area
for sample code.</para>
</content>
</section>
<section><!--H2-->
<title>Handy links</title>
<content>
<list class="bullet">
<listItem>AyaNova Development / API / SDK <externalLink>
<linkText>support forum</linkText>
<linkUri>http://forum.ayanova.com/forumdisplay.php?42-Development-SDK-API</linkUri>
</externalLink></listItem>
<listItem>AyaNova API <externalLink>
<linkText>documentation</linkText>
<linkUri>http://api.ayanova.com/</linkUri>
</externalLink></listItem>
<listItem>Download <externalLink>
<linkText>AyaNova Plugins</linkText>
<linkUri>http://www.ayanova.com/plugins.htm</linkUri>
</externalLink> including AyaScript</listItem>
<listItem>c# language <externalLink>
<linkText>specifications</linkText>
<linkUri>http://msdn.microsoft.com/en-us/library/aa645596(VS.71).aspx</linkUri>
</externalLink></listItem>
<listItem><externalLink>
<linkText>Stack Overflow</linkText>
<linkUri>http://stackoverflow.com/</linkUri>
</externalLink>
questions and answers for programmers</listItem>
<listItem><externalLink>
<linkText>CodeProject.com</linkText>
<linkUri>http://www.codeproject.com/</linkUri>
</externalLink>
- questions answers and articles for programmers</listItem></list>
</content>
</section>
<section><!--H2-->
<title>Free development environments</title>
<content>
<para>While an integrated development environment is not required to work with
AyaScript it can be useful to have an ide on hand to get the syntax and
spelling correct for more complex scripts. We use Visual Studio Professional
in-house however there are a couple of free alternatives available:</para>
<list class="bullet">
<listItem>Microsoft® Visual C#® 2008 <externalLink>
<linkText>Express Edition</linkText>
<linkUri>http://www.microsoft.com/express/Windows/</linkUri>
</externalLink></listItem>
<listItem><externalLink>
<linkText>#develop</linkText>
<linkUri>http://www.icsharpcode.net/OpenSource/SD/</linkUri>
</externalLink> (short for SharpDevelop) is a free, open source
IDE for C#</listItem></list>
</content>
</section>
<section><!--H2-->
<title>Special thanks</title>
<content>
<para>AyaScript uses the excellent <externalLink>
<linkText>CS-Script</linkText>
<linkUri>http://csscript.net/</linkUri>
</externalLink>© script execution engine by Oleg
Shilo.</para><!-- end sidebar -->
&#160;<!-- end page -->
</content>
</section>
<relatedTopics>
</relatedTopics>
</developerConceptualDocument>
</topic>