UXC Project - JQuery Components Library

项目愿景

UXC Project 的目标是建立一套 易于使用、功能齐全、编码规范、接口规范 的 jquery 组件库

文档和资源链接

https://github.com/suchesqiu/360UXC

http://uxc.btbtd.org/

http://uxc.btbtd.org/document.html

http://uxc.btbtd.org/uxc_docs/classes/window.UXC.html

uxc_docs/classes/window.UXC.html

http://360.75team.com/~qiushaowei/uxcjs/

http://360.75team.com/~qiushaowei/uxcjs/document.html

http://360.75team.com/~qiushaowei/uxcjs/uxc_docs/classes/window.UXC.html

https://portal.src.corp.qihoo.net/svn/AppDevFe/trunk/jquery

如何获取最新发布版本

  1. git clone https://github.com/suchesqiu/360UXC.git 如果发现 https clone 比较慢的话, 可以尝试一下 http git clone http://github.com/suchesqiu/360UXC.git
  2. https://github.com/suchesqiu/360UXC/archive/master.zip

如何使用

  1. 加载 jquery 1.9.1 && UXC 资源管理器
    <script src="./lib.js"></script> <script> //声明组件库所在路径, 这个属性组件库加载时会自动识别, 如无特殊需求不需要显式声明 //UXC.PATH = '/uxcjs/'; UXC.debug = true; //是否显示调试信息 UXC.use( 'Calendar, Valid, Panel' ); //导入常用组件 $(document).ready(function(){ //在这里可以开始使用导入的组件 }); </script>
  2. UXC.use 资源管理器的使用

    _demo

    http://uxc.btbtd.org/_demo

    http://360.75team.com/~qiushaowei/uxcjs/_demo

  3. 组件的使用请查看 API 文档

    uxc_docs/classes/window.UXC.html

    http://uxc.btbtd.org/uxc_docs/classes/window.UXC.html

    http://360.75team.com/~qiushaowei/uxcjs/uxc_docs/classes/window.UXC.html

组件库结构说明

library root                        //组件库所在目录
├── document.html                   //本说明文档
├── lib.js                          //lib.js = jquery.js + common.js + UXC.js
├── jquery.js                       //jquery 1.9.1
├── common.js                       //一些通用函数,组件中用到的函数如果出现在多个地方,可以考虑转移到这里
├── UXC.js                          //UXC 资源控制器
├── _demo                           //UXC 资源控制器 使用例子
├── uxc_docs                        //UXC 组件库 API 文档
├── comps                           //comps 目录存放由UXC Project开发人员开发的jquery组件
│   ├── Calendar                    //日历组件
│   ├── Form                        //表单常用功能组件
│   ├── LunarCalendar               //农历日历组件
│   ├── Panel                       //弹框组件( UXC.Panel, UXC.alert, UXC.confirm, UXC.Dialog, UXC.Dialog.alert, UXC.Dialog.config );
│   ├── Tab                         //Tab组件
│   ├── Test                        //测试组件, 新建组件时,直接拷贝这个目录变更一个名字
│   ├── Tips                        //Tips组件
│   ├── Tree                        //树菜单组件
│   └── Valid                       //表单验证组件
├── plugins                         //这个目录存放一些常用的第三方脚本
│   ├── base64.js
│   ├── jquery.form.js
│   ├── json2.js
│   ├── md5.js
│   ├── rate
│   └── swfobject.js
├── widgets                         //这个目录存放一些HTML小部件
│   └── IframeUpload
└── tools                           //这个目录存放一些有用的工具
    ├── generate_yuidoc_for_uxc.sh  //生成API文档shell
    ├── node_remove_View_Model.js   //nodejs API 文档过滤脚本
    └── php                         //PHP 工具,列目录用

                            

面向开发者的结构说明

源码托管使用 git, 项目主页: https://github.com/suchesqiu/360UXC

目前 git 上面有三个主要分支:

  1. master 分支,这是主分支,发布新组件都应该提交到 master分支,
    https://github.com/suchesqiu/360UXC
  2. master_compressed 分支, 这个分支与master分支的内容保持一致,唯一不同之处就是这个分支的所有源码都是经过压缩的,
    https://github.com/suchesqiu/360UXC/tree/master_compressed
  3. dev 分支, 这个分支是 qiushaowei的开发分支,dev 分支开发完的组件都会提交到 master 分支
    https://github.com/suchesqiu/360UXC/tree/dev

编码规范和注释规范

  1. http://dojotoolkit.org/reference-guide/1.9/developer/styleguide.html

  2. http://yui.github.io/yuidoc/syntax/index.html

    写注释时请务必按照YUIDoc规范书写, API文档是从注释里直接生成的~

如何协作开发

  1. 你需要注册一个 github 的帐户, 到这里注册: https://github.com/
  2. 下载对应操作系统的 git 客户端
    1. windows 系统

      推荐使用: TortoiseGit https://code.google.com/p/tortoisegit/

      或者到 github 官网下载官方客户端

    2. 其他操作系统

      不用windows的同学自己会知道怎么弄的~

  3. 从开发人员列表中找到 qiushaowei 的联系方式~ 告知你的github用户名

    然后 qiushaowei 会把你加入到开发人员列表中

    在没有加入到开发人员名单之前, 你可以 clone 项目, 但是没有提交更改的权限

  4. 建立属于你自己的开发分支进行开发

    1. https://github.com/Kunena/Kunena-Forum/wiki/Create-a-new-branch-with-git-and-manage-branches

    2. http://joelabrahamsson.com/remote-branches-with-tortoisegit/

    注意: 你建立的分支应该是 master 的一个 copy, 不是 dev 的 copy

  5. 关于开发分类: 组件(comps), jquery 插件(plugins), 小部件(widgets)

    1. 如何开发组件(comps)
      什么是组件?
          组件在UXC项目里是指那些需要 使用 new 关键字初始化的 应用.
      
      组件应该存放在那个目录?
          目前组件的存放目录规划位于 libpath/comps 目录
      
      组件的基础结构?
          每个组件都有自己的独立文件夹, 并且脚本名称大小写与文件夹保持一致
      
      开始开发组件
          请查看 libpath/comps/Test 目录, 这是个示例组件, 
          开发组件时可以直接copy Test组件然后改一下文件和内容命名
          Library/comsp/Test          示例组件
          ├── _demo                   效果演示
          │   ├── index.php           列目录资源的PHP
          │   └── simple_demo.html    演示默认例子
          ├── index.php               列目录资源的PHP
          ├── res                     资源目录, 这个目录规划是可以各种themes, 每个 themes有自己对象的目录
          │   └── default             默认 themes
          │       ├── style.css
          │       └── style.html
          └── Test.js                 组件的js脚本, 命名应该与组件目录大小写保持一致
      
      
    2. 如何开发jquery插件(plugins)
      什么是jquery插件?
          jquery插件在UXC项目里是指那些 扩展 jquery 对象的应用
      
      jquery插件应该存放在那个目录?
          目前jquery插件的存放目录规划位于 libpath/plugins
      
      jquery插件的基础结构? 
          jquery 插件可以是独立的一个脚本, 或者是带有自己的文件夹
          
          example:
              libpath/plugins/json2.js
              libpath/plugins/rate/rate.js
      
      jquery插件的开发规范请见官方文档:
          http://learn.jquery.com/plugins/basic-plugin-creation/
      
    3. 如何开发小部件(widgets)
      什么是小部件?
          小部件在UXC项目里是指那些不是 jquery组件 也不是 jquery插件的应用
          比如目前小部件里的 IframeUpload
      
          BaiduEditor, FCKEditor, swfupload 也可以归类到 小部件里
      
          那到底什么是小部件? 
          简单的说法就是用 javascript写的小工具, 但不限于 javascript小工具~
          也可以是其他语言写的小工具~ 比如 as, java~
      
      小部件应该存放在那个目录?
          目前小部件的存放目录规划位于 libpath/widgets
      

如何发布资源

当你写了一个组件想发布的时候应该怎么办?

  1. 为了保证项目的质量, 要发布组件的时候请对组件进行一次全面的review, 测试一下各种应用场景看看有没有不可预知的bug~
    通常测试的场景越多总会发现各种奇怪的bug~
  2. 注释也是必不可少的~
    目前 API 文档是使用 YUIDoc 从注释里生成的
    所以注释务必写详细点
  3. 在你自己的专属分支里生成 API 文档, 看看文档效果是否符合预期

    生成文档需要的运行环境: nodejs, yuidocjs(nodejs plugin)

    1. linux 系统
      cd libpath/tools
      sh generate_yuidoc_for_uxc.sh
                                                      
    2. windows 系统
      cd libpath/tools
      generate_yuidoc_for_uxc.sh
                                                      
    3. 生成文档的默认识别路径是 libpath/*

      生成后的文档存放在 libpath/uxc_docs

  4. 确保一切无误后, 把要发布的组件 copy到master分支里
        当前的开发分支不是master分支, 怎么 copy到master分支里?
        最简单的方法就是用 git clone 获取一个新的 master分支
    
    如果你已经获取过一个 master分支, 记得先 git pull origin master 更新一下 master分支
    
    然后在master分支里运行一下 文档生成脚本~
    
    再次检查一下文档和代码是否正常
    没有问题当然就是提交更改了~
                                    

注意: 开发组件的时候应该在自己的专属分支里进行, 发布的时候再单独合并到 master 主干

开发需求

  1. ./tools/开发需求.txt
  2. http://add.corp.qihoo.net/pages/viewpage.action?pageId=8036850

沟通讨论

  1. 81514206
  2. 67024282
  3. uxc#btbtd.org

开发者名单

  1. 908202921(qq), 133382778(飞信), suches#btbtd.org, http://btbtd.org